软件工程之代码规范

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

业务细节

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

业务常量与公共逻辑

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

单条与多条逻辑分开

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

命名问题

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

避免模型之间的互相调用

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

接口细节

基础数据

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

关联数据

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

接口

命名规范

大致如下

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

模型规范

组成部分
  • 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
        }]
    }
}
注意事项

前台接口的一些需要注意的东西,比如控制器里面格式,每次有变化的时候,我们都得注意是否需要修改

此外,吐出的数据能够运算出来的数据,都应把这种运算性能尽量交给前端来做
比如,给出了参与人数、通过人数,则通过率由前端来运算
总的来说,前端能很容易拿到的,或者各端UI展现形式不一样的,后端能不给就不给

各端UI展现形式

现在有以下前端可以得到的数据

  • 考试人数
  • 通过人数

如,H5 只需要展示这两项数据
但是 APP 还需要考试通过率(通过人数/考试人数 * 100%)
这时候 APP 这边是可以直接可以运算出来的
那么后端 API 就不用专门吐给 APP 端需要的这数据了

注释规范

自译性

TODO

通用注释

TODO

注:若无特殊说明,文章均为云天河原创,请尊重作者劳动成果,转载前请一定要注明出处