您的位置:晶晶的博客>速记>接口api开发中关于统一规范的一些非技术实践归纳

接口api开发中关于统一规范的一些非技术实践归纳

这是笔者长期实践过程中自己归纳总结的一些关于规范的实践要点记录,看自己的笔记已经形成了一篇文章的规模就分享出来,后续有补充会及时更新。

代码里逻辑判断与文案提示分离

{
    "msg":"订单不存在",
    "code":10001,
    "data":{

    }
}
{
    "msg":"商品已下架",
    "code":10002,
    "data":{

    }
}

上方两处返回结果中,code值不同表示不同的含义,做好全局唯一编码,注意不要导致重复,数字的编码可以考虑使用前缀作为不同业务类型的区别,譬如:1xxx表示订单类,2xxx表示商户商品类 等等

另外,对于编码确定后要做好统一的表格文档,便于快速查找和核对,差不多如下:

编码 说明 备注
1001 订单不存在
1002 商品已下架

这样实践的目的很简单,业务方(api接口调用方)可通过code进行业务调度,而msg文案则可以直接显示,甚至可以通过统一的错误文案服务,使用code去换文案。

业务错误、异常bug错误捕获区分

业务错误和程序错误被捕获的异常是不同的,需要做好区分。

异常捕获的错误信息尽量完整,便于追踪排查。

严禁字段透传和无控制字段返回

透传(透明传输)即不做任何字段的更改直接发送给了调用方。

对于从Db或微服务模块读取出的源数据,严禁不经处理就直接传递给了调用方。

例如从MySQL中读取出了如下数组数据:

[
    {
        "id":1,
        "name":"jing",
        "phone":13800138000
    },
    {
        "id":2,
        "name":"yang",
        "phone":13800138001
    }
]

严禁直接就传递给了客户端,而是要经过处理定制后发送给客户端,纵使发送给客户端的字段与读取出来的字段一摸一样也要执行一遍赋值后再返回。

可空字段、对象严格约定好规则

{
    "id":1,
    "config": {
        "is_term":true,
        "time":"2019-08-30 23:23:23"
    }
}

假如上述结构中config字段是可能为空的,为空的表示方法有多种如下:

{
    "id":1,
    "config": {}
}

{
    "id":1,
    "config": []
}

{
    "id":1,
    "config": ""
}

{
    "id":1,
    "config": null
}

{
    "id":1
}

不讨论哪种表示为空的方法最优雅、最牛逼,而是必须确定好一种字段值可空时空值的表示方法,一个项目中不要存在多套规则。

同理null''true1false0都要约定好统一的一套规则;而不是各人有各人的写法。

统一字段名称格式

字段名称的格式统一可以避免不少麻烦,要做到这一点很简单也很难,简单是因为只要团队建立起统一的规则就可以实施,难是大如京东这样的公司里字段都很难做到统一同一套规则,历史遗留问题很难在短期内做到完全的收敛统一。

字段命名规则有多套:

  • CamelCase 驼峰命名法,首字母小写驼峰命名,例如orderStatus
  • PascalCase 帕斯卡命名法,例如OrderStatus
  • SnakeCase蛇形命名法,有些又称之为下划线命名法UnderScoreCase,例如order_status
  • KebabCase 连字符命名法,例如order-status
  • Hungarian notation 匈牙利命名法,变量=属性+类型+对象描述,其中每一对象的名称都要求有明确含义,可以取对象名字全称或名字的一部分,这个命名法比较复杂,微软用的多,也是被喷的最多的,有争议的不需要浪费精力直接舍弃。

哪种命名方法更高级?哪种命名方法更优雅?有空争论这个不如去学一门新语言新技术,学好了还阔以拿高薪,乌龟的屁股(龟腚)一套团队必须遵循的,大家统一使用即可。

京东微信端:PascalCaseCamelCaseSnakeCase混用,也还有诸如trialproduct这样的奇葩存在,混乱

淘宝pc端:似乎统一做的很好,均是CamelCase

转载请注明本文标题和链接:《接口api开发中关于统一规范的一些非技术实践归纳

哟嚯,本文评论功能关闭啦~