目录
目录README.md

开发者说明

一、接口规范(废弃)

统一使用Restful 风格(废弃)

Rest架构中请求表现为”宾语+谓语”,宾语体现在请求url中,谓语对应为请求方法

  1. 路径(Endpoint)
    每个url代表一种资源(resource),所以url中不能有动词,只能有名词,名称一般写成复数形式
    示例:
    http://container.ccyunchina.com/environments
  2. 请求方法说明
    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}:删除某个指定环境的指定工作负载
  3. 条件过滤
    如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
    参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /environments/{id} 与 GET /environments/{id}?id=ID 的含义是相同的。
  4. 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 - 服务器发生错误,用户将无法判断发出的请求是否成功。
  5. 幂等性
    除了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(“名称”);

关于

统一运维平台

264.0 KB
邀请码
    Gitlink(确实开源)
  • 加入我们
  • 官网邮箱:gitlink@ccf.org.cn
  • QQ群
  • QQ群
  • 公众号
  • 公众号

©Copyright 2023 CCF 开源发展委员会
Powered by Trustie& IntelliDE 京ICP备13000930号