hugh 的个人博客

bff接口设计规范

接口规范

URL格式

  • 域名限制

接口有必要区分对内对外, 通过nginx或者业务层进行区分限制

  • 对外: xx.xxx.com
  • 对内:xx.xxx.net
  • path命名规范

**/{sys_name}/{logic}/v{version}/{operation} **定义的api一般包含几个部分,

sys_name: 可选, 一般用于在nginx上作为一个系统名称区分服务。 如xx.xx.com/nbs : 表示的是走nbs服务。 如果挂载的子系统比较多,建议部分名称可以比较明确的识别出系统

Logic: 业务逻辑分组, 一个系统能会包含很多的业务,该部分表示业务的内容

Operation: 操作, 操作表示当前这个api表示的实际行为,如/product/v1/spu_create

Version: 版本, 用于接口平滑升级需要,版本可以简单设计,一般接口不兼容升级的场景并不多,如v1,v2...

规范:

  • 仅可使用小写字母、数字、下划线
  • 单词间使用下划线连接
  • Operation: 资源+_+操作动词

为什么要这样设计Operation, 我们可以根据特点的api规则进行权限控制,如//_create 限制写权限

常见的操作动作有哪些:

方法HTTP 请求体HTTP 响应体
xxx_list资源 列表
xxx_get资源
xxx_create资源资源
xxx_update资源资源
xxx_delete

请求体规范(Request)

  • content_type使用

  • application/json (todo)

  • 参数规范

    • 仅可使用大小写字母, 数字
    • 使用小驼峰命名法

Good and bad case

// good

{

  "userId": "xxx",

}

// bad

{

  "user_id": "xxx",

}
  • 请求体内容

    • 用户、权限相关信息不应该提交, 应由接口通过登陆态进行获取和二次验证
    • 不需要的数据不提交, 接口应定义明确的提交字段, 多提交的字段不应处理(可以记录优化)。

响应体规范(Response)

  • content_type

  • application/json

  • 资源类

  • 缓存

  • js/css/其他资源类

    • 强制缓存
  • Html

    • 协商缓存
  • Apis(bff针对前端的)

    • 服务端不缓存, 客户端可选缓存
  • 跨域

  • cors规则 TODO

  • 响应格式

{

    code: number, // 0 成功

    data: object|null, // 成功后获取的数据对象

    message: string // 错误后的错误信息

}
  • code规则(todo,细化或者参考code错误码系统)
    • 0: 成功
    • 3xx: 登陆错误
    • 4xx: 权限错误
    • 5xx~∞: 业务按分组给出错误内容
  • 响应内容(data)
    • 最小化需要的字段, 一方面是减少网络负担,一方面是提高安全防范
    • 使用小驼峰命名法

安全规范

  • 登陆校验

    • 区分内外网,走sso、passport 权限
  • 接口权限

    • 对接kani等权限
  • 操作日志

    • 对接内部日志系统, 可以自建,用于记录用户操作行为(一般在内部专家系统)
  • 安全防御

    • Xss
      • 不信任任何提交内容, 不只是做普通的字段校验, 也需要做安全性校验
    • 越权
    • ssrf
    • csrf
      • 那些接口需要token防御csrf

​​


标题:bff接口设计规范
作者:hugh524
地址:https://blog.uproject.cn/articles/2021/08/29/1630250098108.html