服务端的规范设计

前言

后端开发的正确打开方式是先将项目规范设计好，然后再将项目文档（接口文档）写好，最后才开始编码！

项目结构规范

结构图

结构设计

Controller（访问控制转发层）

1. 校验token；
2. 用户权限校验；
3. 用户角色校验；
4. 参数校验；
5. 数据校验；
6. 数据序列化；
7. 轻业务逻辑；
8. 异常兜底；
9. 使用 DTO<VO> 或者 DTO<BO> 作为对外领域模型；
10. 一个 Controller 应一个 Service

Service（业务逻辑服务层）

1. 复杂的业务编排逻辑处理；
2. 捕捉异常；
3. 复用性低；
4. 使用 DTO<BO> 作为领域模型（Business Object 业务对象）；
5. 一个 Controller 应一个 Service ；

Mannager（通用业务处理层）

1. 对第三方平台封装的层，预处理返回结果及转化异常信息；
2. 对 Service 层通用能力的下沉，如缓存方案、中间件通用处理；
3. 与 DAO 层交互，对多个 DAO 的组合复用；
4. 复用性高；
5. 可以是单个服务，也可以是复合服务，比如多表查询；
6. 使用 DTO<BO> 作为领域模型；

DAO（数据持久访问层）

Redis
Cache
Service
DO

表结构规范

1. 数据库表的命名 t_ 为开头；
2. 表的主键有两个，表序号 id ，用户ID user_id ，分布式的全球唯一标识 only_id ；
3. 字段命名 下划线规则 ，无大写，下划线分离开单词。

请求规范

1. 创建使用 POST 请求；
2. 删除使用 DELETE 请求；
3. 更新使用 PUT 请求；
4. 查询使用 GET 请求；

接口规范

如关于用户的操作：

创建用户

• 请求方法： POST
• 请求路径： https://aip.huangdayu.cn/v1/users

查询单个用户数据

• 请求方法： GET
• 请求路径： https://aip.huangdayu.cn/v1/users/{user_id}

更新用户数据

• 请求方法： PUT
• 请求路径： https://aip.huangdayu.cn/v1/users/{user_id}

删除用户

• 请求方法： DELETE
• 请求路径： https://aip.huangdayu.cn/v1/users/{user_id}

查询用户列表

• 请求方法： GET
• 请求路径： https://aip.huangdayu.cn/v1/users

查询用户名称

• 请求方法： GET
• 请求路径： https://aip.huangdayu.cn/v1/users/{user_id}/name

说明

v1：为接口版本号 users ：为具体对象的名词复数

URL标准

• URL 的命名 必须 全部小写，单词之间用 _ 分隔开
• URL 中资源（ resource ）的命名 必须 是名词，并且 必须 是复数形式
• 必须 优先使用 Restful 类型的 URL
• URL 中不能出现 - ， 必须 用下划线 _ 代替
• URL 必须 是易读的
• URL 一定不可 暴露服务器架构

入参规范

1. 使用 application/x-www-form-urlencoded 与 application/json;charset=UTF-8 并存。
2. 使用 Token 身份认证，解决判断和权限鉴定，采用 AOP 面向切面编程认证 Token ;
3. 请求携带的Token保存在Http Header的 Authorization 字段中，例如：Authorization: Bearer token…；
4. 分页页数使用 page 字段，例如：page=3;
5. 每页的数量使用 per_page 字段，例如：per_page=10；
6. 指定数量使用 limit 字段，例如：limit=10；
7. 返回结果 排序 属性使用 sortby 字段，例如：sortby=”大鱼叔叔”；
8. 返回结果排序顺序使用 order 字段，例如：order=asc

出参规范

1. 响应Content-Type使用标准的 application/json;charset=UTF-8
2. 响应Header使用标准的 HTTP Status Code ；
3. 状态码： code 使用 int （内部定义规范）;
4. 状态标识： msg 使用 String （内部定义规范）;
5. 状态说明： desc 使用 String （内部定义规范）;
6. 响应数据体： data 使用 List<T> ;
7. List 中包含分布式全球唯一标识 only_id ；
8. request_id 和 server_time 为非必须；

参数校验规范

存在争议

防御派

方法应该为自己负责，我不能保证调用者是否进行了校验，所以我必须要进行校验，从而保证程序的健壮性。

简约派

方法应该校验，但是不应该重复校验。重复校验产生了冗余的代码，导致程序可读性差。

本规范标准

开发自用方法

权限： private , protected , default

参数是可控的，在方法中不必校验参数合法性，调用者在调用之前应确认传入参数的合法性。

开发公共方法

权限： public

参数是不可控的，在方法中必须校验参数的合法性，因为无法保证调用者的行为和传入参数的合法性。

其他规范

1. 前后端分离架构
2. Web / App ( Android / iOS )/ Open (对外开放 OAuth )共用一套接口；
3. 使用 JSON 作为交互协议；
4. 使用 Swagger 作为接口文档；
5. 使用 HATEOAS 构建 RESTful Web API JSON ;
6. RESTful API 命名使用名词复数；

参考文献