文章目录
一、接口规范
业务即文档
- 控制层采用 REST 规范，可以将每个业务中心理解为一个超大的 JSON 文档，通过 URI 在文档中来定位资源，通过 Http 动词完成增删查改操作
{
members: [
{
id: 100000001,
mobile: 18900000001,
addresses: [
{
id:100000001, detail: 美创总部
}
],
tags: [100000001,100000002],
pointRecords: [
{id:100000001}
]
},
{
id: 100000002,
mobile: 18900000002,
addresses: [
{
id:100000002, detail: 美创总部
}
],
tags: [100000003],
pointRecords: [
{id:100000003}
]
}
]
}
URL 规范
第一步是通过 URL 在文档中对资源进行定位
- URL 是统一资源定位符，用于在文档中定位资源。如果资源的单词是包含多个，采用驼峰形式，例如积分流水，采用：pointRecords
- 看几个常见的URL
-
https://cmms3.meicloud.com/webadmin/vip/members/100000001定位到会员 id 为 100000001 的会员对象 -
https://cmms3.meicloud.com/webadmin/vip/members/100000001/addresses/100000002定位到会员 100000001 下的 id 为 100000002 的会员地址对象（不推荐、推荐下面这个） -
https://cmms3.meicloud.com/webadmin/vip/addresses/100000002定位到 id 为 100000002 的会员地址
-
- 从上面的例子看出，URL 包含以下几部分
- 协议，域名，端口
- 业务应用：上面的 webadmin 就是应用
- 业务模块：vip 是业务模块，表示会员中心
- 具体的资源：具体中心的资源定位，包括复数名字和唯一资源定位符（ID）
- 对于操作会员地址，为什么不是先定位到会员再定位到地址？
- 主要是通过地址的唯一标识也能定位到，所以直接简化为直接通过地址id定位到地址对象。
动词规范
第二步就是通过动词，对资源进行操作
- 标准动词
- 增加：
POST https://cmms3.meicloud.com/webadmin/vip/members - 删除：
DELETE https://cmms3.meicloud.com/webadmin/vip/members/100000001 - 根据ID查询：
GET https://cmms3.meicloud.com/webadmin/vip/members/100000001 - 修改：
PATCH https://cmms3.meicloud.com/webadmin/vip/members/100000001（小程序不支持 PATCH ，改用 PUT 亦可）
- 增加：
- 自定义动词
- 如果对应的操作，无法抽象成标准的 http 动词，允许定义自定义动词。为了 URL 规范，需要维护好自定义动词表。
- 自定义动词采用 http POST 方法，在 URL 后面，通过动词的方法来定义。例如：
- 根据条件查询：
POST https://cmms3.meicloud.com/webadmin/vip/members:search - 批量更新：
POST https://cmms3.meicloud.com/webadmin/vip/members:batchUpdate - 锁定操作：
POST https://cmms3.meicloud.com/webadmin/vip/members/100000001:disable - 维护好自定义动词表，后续涉及的自定义动词都从动词表出，如果没有，才考虑新增，并维护进动词表。目前系统上用的自定义动词表有：
- 分页查询：
xxx:search，这个本来可以用GET方法，由于条件可能较多，就没有采用 GET方法+queryParmeter来实现。 - 批量操作：
batchXXX， 例如： batchGet，batchUpdate，batchDelete，batchCreate - 其它操作： 例如
:login，:lock，:unlock，:disable，:enable，:approve（审批） - 统计：
stat
- 根据条件查询：
二、安全
令牌
- 令牌采用
JWT。需要了解 JWT 的优缺点才能更好地使用 JWT，下面只列出主要的优缺点，可以再找文章去了解 -
优点：- 无状态，不需要存储
- 可扩展，可以通过 payload 对令牌的内容进行扩展
- 依赖于算法对签名做加密，安全
-
缺点：- 过期时间固定，不可延长，如果要延长，需要重新创建令牌
- 无法销毁，对 jwt 令牌的加入黑名单，需要引入额外的存储
-
令牌内容：- jwt 是明文的，令牌包括，header，payload，signature 三部分，前面两部分都是明文，可以直接进行 base64 解码，拿到明文的内容。
-
令牌的正确用法：- 签名校验，因为令牌本身是明文的，靠的是令牌的signature部分，如果不对签名进行校验，令牌是可以被伪造的。
- 令牌里包含的应该都是大部分接口需要用到的，并且基本不会修改的字段。例如 memberId，手机号码，unionId，openid，用户类型
-
一些错误使用的例子：- 将某个业务字段加入到令牌中，例如当前用户的积分数。 积分数是会变化的，如果变化了，那令牌里的内容就不正确了。
- 只保留一个会员id，其它信息从redis获取。这样就没有用上jwt令牌的特性，要完成业务基本是要依赖于缓存。
-
令牌图解
接口加密
- 在 C 端的活动运营过程中，发现有很多薅羊毛的工作室，为了避免接口被刷，需要对接口的请求报文和响应报文做加密，是通过在
控制层做接口拦截来实现的。 - 大概的就是
对请求的报文做对称性加密，额外增加签名字段做非对称加密，对接口响应结果做对称加密。 - 目前在项目上上的方案是，增加签名，对签名做校验，签名只和当前时间戳，用户令牌有关，和请求参数无关。
接口权限
- 接口权限目前是在控制层处理的，C 端功能不涉及接口权限，B 端（管理后台）功能会涉及数据权限，数据权限的控制是通过拦截器进行拦截。
数据权限
- 无论什么时候都要假设，前端也可以是 postman，也就意味着参数可以随意被篡改，所以在控制层做好数据权限就非常重要，如果接口加密做好了，这个阶段的风险会稍微降低。
- 以下几点要注意，第 1、2 点要特别注意
- 对于查询和创建接口，需要
获取当前用户作为条件，查询或者创建当前用户的数据 - 对于根据 id 操作的接口，包括根据 id 查找对象，根据 id 更新或删除对象等，需要对查回来的结果，在
控制层需要判断数据归属当前用户后对才允许对数据进行操作 - 涉及用户资产的接口，不允许设置为匿名访问
- 匿名接口都要考虑如果非匿名情况下访问会不会有差异
- 对于查询和创建接口，需要