软件工程之代码规范

2019-11-26 16:38:55 语法专题 3124 0

业务细节

以下内容,开发前必须注意

业务常量与公共逻辑

如,某个表字段的枚举值,因为属于业务含义,所以应该把它放到Model里
特征: 因为他们可能被多个Model用到
使用方案: 方式1:书写一个基类Model去继承; 方式2:书写一个静态Model类

单条与多条逻辑分开

要求 Model 层与 Data 层,都将各自的单条数据与多条数据逻辑分开
(单条数据只会扫一条多条扫,可能不止一条.用多条的逻辑去取一条,在逻辑上是不可取的)

命名问题

代码自译性
- 英文翻译与代码含义应无差别对应
- 在CGI模式下,不应因取出数据量大,而简化字段名
- 接口输出数据,应与数据库内字段无差别对应
- 方法名返回值应与返回预期相对应
  - 函数名开头,小结西如下
    - validate
      - 无返回值
    - check
      - 应返回 Boolean
    - get 相关
      - 注:如果是在Model层,则内部可以调用 validate、check
      - get
        
        应返回单条数据
      - getList
        
        应返回同类型的多条数据

避免模型之间的互相调用

如果Model之间都是静态方法
则可以尝试调用,否则需要单例化Model调用
总之得防止它们直接互相调用导致循环调用

接口细节

基础数据

通常是一张有挺多自有属性表
如，用户的详情表

关联数据

通常是让不同基础数据之间建立关联的数据
如，打包购买表，这个表基本是存的商品与包的关系

接口

命名规范

大致如下

info
- 基础数据
detail
- 基础数据及一些关联数据
add
- 基础数据,添加单个
- 关联数据,得注意是否可以添加多个,如果能多个,尽量兼容添加多个
delete
- 基础数据,删除单个
- 关联数据,得注意是否可以删除多个,如果能多个,尽量兼容删除多个
edit
- 基础数据,修改单个
- 关联数据,得注意是否可以修改多个,如果能多个,尽量兼容添加多个
list
- 分页式
  - 后台分页条（含总计条数）
  - 前台上拉加载（不含总计条数）
- 全量(列表数据)
小接口细拆的场景
- 常见为状态的反转:上/下线、勾选/取消等等
  - 如:上下线
    - 应拆分为:2个接口
      - 命名 online、offline
吐出字段规范
- 先看看以前同模块中，有没相同的字段，如果有，就用以前接口中的字段为为准

模型规范

组成部分

code
- 错误码
  - 0~999 公共错误码 - HTTP型
    - 200 正常
      - 如，请求成功
    - 401 访问权限
      - 如，您的登录信息已失效，请重新登录
    - 404 资源不存在
      - 如，对应数据在库中不存在
    - 500 内部错误
      - 如，服务器内部未知错误（对外文案：服务繁忙，请稍候重试）
    - 504 操作超时
      - 如，某个接口会通过网络协议调用其他内部服务的功能导致超时
  - 1000~1999 公共错误码 - 通用型
    - 1001 您访问太快，请客官稍候重试
    - 1002 传入参数不正确
  - 2000~9999 业务逻辑错误码 - 可预见
    - 2001 帐号不存在
    - 2002 用户登录日志，写入失败
message
- 错误码描述
  - 输出对应错误码的文案
data
- 数据对象
  - 使用对象为方便接口扩展数据项

{
    "code": 200,
    "message": "请求成功",
    "data":
    {
        "categories": [
        {
            "id": 17,
            "title": "HTTP",
            "total": 6
        }]
    }
}