请求方法说明 GET(SELECT):从服务器取出资源(一项或多项)。 POST(CREATE):在服务器新建一个资源。 PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。 PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。 DELETE(DELETE):从服务器删除资源。 示例: GET /environments:列出环境列表 POST /environments:新建一个环境 GET /environments/{id}:获取某个指定环境的信息 PUT /environments/{id}:更新某个指定环境的信息(提供该环境的全部信息) PATCH /environments/{id}:更新某个指定环境的信息(提供该环境的部分信息) DELETE /environments/{id}:删除某个环境 GET /environments/{id}/workloads:列出某个指定环境的所有工作负载 DELETE /environments/{id}/workloads/{id}:删除某个指定环境的指定工作负载
条件过滤 如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。 参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /environments/{id} 与 GET /environments/{id}?id=ID 的含义是相同的。
Http状态码 成功状态码: 200 OK - 请求成功。 201 CREATED - 用户新建数据成功。 204 NO CONTENT - 请求成功,但响应中没有消息体 错误状态码:
400 INVALID REQUEST - 用户发出的请求有错误 401 Unauthorized - :表示用户没有权限(令牌、用户名、密码错误)。 403 Forbidden - 表示用户得到授权(与401错误相对),但是访问是被禁止的。 404 NOT FOUND - 用户发出的请求针对的是不存在的记录,服务器没有进行操作。 405 Method Not Allowed 409 Conflict - 表示要创建的资源已经存在 422 Unprocesable entity - 当创建一个对象时,发生一个验证错误。 500 INTERNAL SERVER ERROR - 服务器发生错误,用户将无法判断发出的请求是否成功。
在Controller层的接口方法(增、删、改)上使用@OperationLog 注解类,@OperationLog中有以下属性: message 日志信息,必需字段,示例 “删除用户”、”新增用户” idField id字段名,非必需字段,默认值为”id”,与entityClass、nameField配合使用,如果方法入参中取不到操作对象名称,比如删除接口一般情况下入参只有操作对象id,那么在Spring data JPA中可以通过id和entityClass从数据库中查询到实体对象,实体对象中必然有操作对象名称,通过id查询到的实体对象使用#oldData表示。 示例 “userId”、”user.id”、”user.role.id”,”user.id”表示从入参列表中名为user的对象中取名为id的属性值,”user.role.id”刚表未从入参列表中名为user的对象下的role对象中取名为id的属性值 nameField 名称字段名,非必需字段,示例:”user.name” ,”#oldData.name” entityClass 实体类名,非必需字段,必需为Spring Data Jpa中的管理的实体类,与idField、nameField配合使用,如果方法入参中取不到操作对象名称,比如删除接口一般情况下入参只有操作对象id,那么在Spring data JPA中可以通过id和entityClass从数据库中查询到实体对象,实体对象中必然有操作对象名称,,通过id查询到的实体对象使用#oldData表示。
如果操作对象不是Spring Data Jpa中管理的实体类,入参中也没有操作对象名称信息,那么还可以通过在代码中使用线程池变量(SysOperationLogService.OBJECT_NAME)来传递名称信息,示例: SysOperationLogService.OBJECT_NAME.set(“名称”);
开发者说明
一、接口规范(废弃)
统一使用Restful 风格(废弃)
Rest架构中请求表现为”宾语+谓语”,宾语体现在请求url中,谓语对应为请求方法
每个url代表一种资源(resource),所以url中不能有动词,只能有名词,名称一般写成复数形式
示例:
http://container.ccyunchina.com/environments
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE):从服务器删除资源。
示例:
GET /environments:列出环境列表
POST /environments:新建一个环境
GET /environments/{id}:获取某个指定环境的信息
PUT /environments/{id}:更新某个指定环境的信息(提供该环境的全部信息)
PATCH /environments/{id}:更新某个指定环境的信息(提供该环境的部分信息)
DELETE /environments/{id}:删除某个环境
GET /environments/{id}/workloads:列出某个指定环境的所有工作负载
DELETE /environments/{id}/workloads/{id}:删除某个指定环境的指定工作负载
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /environments/{id} 与 GET /environments/{id}?id=ID 的含义是相同的。
成功状态码:
200 OK - 请求成功。
201 CREATED - 用户新建数据成功。
204 NO CONTENT - 请求成功,但响应中没有消息体
错误状态码: 400 INVALID REQUEST - 用户发出的请求有错误
401 Unauthorized - :表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - 用户发出的请求针对的是不存在的记录,服务器没有进行操作。
405 Method Not Allowed
409 Conflict - 表示要创建的资源已经存在
422 Unprocesable entity - 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - 服务器发生错误,用户将无法判断发出的请求是否成功。
除了PUT和PATCH请求,其它请求需要满足幂等性
二、设计说明
操作日志设计
使用spring aop实现基于注解方式实现,在注解类中传入操作对象名称引用字段,在日志切面类中对于Java 反射从入参或者操作实体对象中取得实际的操作对象名称。
使用说明
在Controller层的接口方法(增、删、改)上使用@OperationLog 注解类,@OperationLog中有以下属性:
message
日志信息,必需字段,示例 “删除用户”、”新增用户”idField
id字段名,非必需字段,默认值为”id”,与entityClass、nameField配合使用,如果方法入参中取不到操作对象名称,比如删除接口一般情况下入参只有操作对象id,那么在Spring data JPA中可以通过id和entityClass从数据库中查询到实体对象,实体对象中必然有操作对象名称,通过id查询到的实体对象使用#oldData表示。示例 “userId”、”user.id”、”user.role.id”,”user.id”表示从入参列表中名为user的对象中取名为id的属性值,”user.role.id”刚表未从入参列表中名为user的对象下的role对象中取名为id的属性值
nameField
名称字段名,非必需字段,示例:”user.name” ,”#oldData.name”entityClass
实体类名,非必需字段,必需为Spring Data Jpa中的管理的实体类,与idField、nameField配合使用,如果方法入参中取不到操作对象名称,比如删除接口一般情况下入参只有操作对象id,那么在Spring data JPA中可以通过id和entityClass从数据库中查询到实体对象,实体对象中必然有操作对象名称,,通过id查询到的实体对象使用#oldData表示。如果操作对象不是Spring Data Jpa中管理的实体类,入参中也没有操作对象名称信息,那么还可以通过在代码中使用线程池变量(SysOperationLogService.OBJECT_NAME)来传递名称信息,示例:
SysOperationLogService.OBJECT_NAME.set(“名称”);