Build Status

Grails Rest Seed

grails rest-api的模板工程,其脱胎于实际的项目经验,集合了我们Grails项目的初始工具包和插件:

  • 数据库
    • postgresql-extensions
    • Hikari连接池
    • postgresql jdbc driver
    • Java 8日期类型支持:grails-java8和hibernate-java8
  • 安全
    • spring-security-core
    • spring-security-rest
  • Servlet容器
    • spring-boot-starter-undertow
  • Migration
    • database-migration
    • liquibase-core
  • build信息
    • gradle-git-properties
  • 阿里云OSS
  • 生成OpenAPI 3说明书

基本配置

  • 日志
    • 应用滚动日志。
    • 独立的SQL调试日志,需设置“DEBUG_SQL”环境变量。
  • 数据库和GORM
    • 启用Hikari连接池。
    • 为Domain Class的id缺省启用PG的sequence。
    • 采用实际DB作为测试基准库,避免因测试和实际DB不一致而引发的意外。
    • 包含了一个示例类,用于展示如何使用PG的丰富类型(jsonb和数组)和java 8日期类型。并且还包括了对应的测试代码。
  • 安全
    • Spring Security和Spring Security Rest配置。
    • User、Role、UserRole初始化。
    • 记录登录历史。
    • 口令加密,采用默认的“bcrypt”算法,其已经具备salt功能。
    • 自定义Login返回的JSON。
  • Build
    • 引入gradle-git-properties后,可以通过actuator暴露git的相关信息,比如commit id, commit message, commit time等等相关信息
    • 该插件会在classpath中产生一个git.properties文件
    • 通过调用GitProperties这个class可以打印出类似于如下的日志: 2018-08-23 18:34:55.265 INFO BootStrap : Application running at commit: 47f5f5a, branch: master, commit time: Mon Aug 20 22:50:05 CST 2018, build time: Thu Aug 23 18:26:56 CST 2018
    • 如果希望启用actuator,需要在application.yml中设置endpoints.info.enable: true
  • Json View
    • 缺省采用deep策略,但激活它有个前提:相应的关联需要被初始化,即在mapping中采用fetch: join。(注意:对单端关联可以采用这一策略,但对于多端,不建议。)
  • 服务端签名后直传阿里云OSS,见此链接
    • 即后端传给前端授权码,之后由前端直接上传OSS,不经过后端。
    • 修改application.yml中【aliyun/oss】部分。

主要功能

  • 用户管理
    • 普通用户:注册、修改密码、重置密码、验证码
    • 管理员:用户管理、冻结、解冻、重置密码、查询
  • 异步任务队列,并且已经内置的任务有:
    • 短信通知

使用指南

  1. git clone
  2. 修改相应的包名,目前包的根为:top.dteam.earth.backend
  3. 自由发挥

生成OpenAPI 3说明书

./gradlew openapi3

在集成测试成功运行之后会在生成OpenAPI 3说明书: build/api-spec/openapi3.yaml。该文件可以在任何支持OpenAPI 3的程序中打开和解析,以及转换其他格式。

如生成html可以用redoc-cli:

npm install -g redoc-cli
redoc-cli bundle build/api-spec/openapi3.yaml
# 浏览器打开 redoc-static.html

其他支持OpenAPI 3的在线编辑器如Swagger EditorStoplight等,都可以打开这个文件在线编辑并且预览。

更多支持OpenAPI 3的工具可以参考OpenAPI.Tools罗列的列表。

增加Spec-Driven API测试用例

和原本的功能测试分开,建议单独放在对应的ApiDocSpec测试中。完整参考文档参见restdocs-api-spec文档以及Spring REST Docs文档

目前restdocs-api-spec有以下几个限制,其中一些官方已经在改进中:

此外,还有很多地方没有开放对应的描述信息修改的接口。完整的OpenAPI 3 Specification参见官方文档以及swagger的教程用例

异步任务队列

异步任务队列需要配合clock使用,只需将任务内容放入Job Domain Class中即可,值得注意之处:

  • 每个任务有相应的Topic,它可视为job的分类。
  • 任务支持回调,需要回调的任务需要在job的body中指明callback属性
  • 任务支持优先级,最小为1,最大为10,越大优先级越高
  • 目前每个任务的重试次数为3次

插入任务之后,clock会负责执行,关于每个Topic的属性,如delay、重试次数等,都由clock的配置决定。目前为统一配置。

目前基于这个设计重新实现了SMS,开发者可自行参考。若某类job的body有格式要求,可参考SMS Topic的实现。

CALLBACK主题任务由clock负责创建,并且优先级最高。

数据库

使用下面的命令初始化数据库和项目用户:

./create_db.sh 数据库名字

缺省创建规则(若数据库名字为db):

  • 产品库:db
  • 测试库:db_test
  • 用户名和密码:db_admin/admin

开发说明

本地开发使用了codenarc, pmd, spotbugs进行代码验证,在提交代码前需要确保测试和代码质量检测均通过:

./gradlew test integrationTest codenarcMain pmdMain spotbugsMain

Grails Rest Seed

Grails REST-API Project Template

Grails Rest Seed Info

⭐ Stars13
🔗 Source Codegithub.com
🕒 Last Updatea year ago
🕒 Created4 years ago
🐞 Open Issues1
➗ Star-Issue Ratio13
😎 AuthorDTeam-Top