服务端的规范设计

前言

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

项目结构规范

结构图

架构图

结构设计

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(数据持久访问层)

  1. 将对象与表结构简历ORM映射关系;
  2. Redis缓存操作;
  3. Cache缓存操作;
  4. 只允许对应的Service访问;
  5. 使用DO作为领域模型;

表结构规范

  1. 数据库表的命名t_为开头;
  2. 表的主键有两个,表序号id,用户IDuser_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-urlencodedapplication/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_idserver_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命名使用名词复数;

参考文献

阿里巴巴Java开发手册(详尽版)
你的项目应该如何正确分层?
RESETful API 设计规范

今日诗词

作者信息