接口定义规范
研发部
2018/01

微服务接口设计采用Restful风格的接口规范,下面是基于Restful风格要求制订的接口设计规范。
1．URI命名规范
不用大写；
用中杠-不用下杠_；
参数列表要encode；
使用名词作为资源名称 <例如,不要在网址中使用动词>；
使用资源集合的概念；
每种资源有两类URI〔接口：
◆资源集合〔例如,/orders；
◆集合中的单个资源〔例如,/orders/{orderId}。
使用复数形式 <使用 ‘orders’ 而不是 ‘order’>；
资源名称和 ID 组合可以作为一个网址的节点；               
    例如,/orders/{orderId}/items/{itemId}；
尽可能的让网址越短越好,单个网址最好不超过三个节点。
    可以使用查询参数代替路径中的restful接口设计节点组合
对Composite资源的访问
服务器端的组合实体必须在uri中通过父实体的id导航访问。
GET /orders/12/items
使用有意义的资源描述；
"禁止单纯的使用 ID!" 响应信息中不应该存在单纯的 ID,应使用链接    或是引用的对象；
设计资源的表述信息,而不是简简单单的做数据库表的映射；
合并表述信息,不要通过两个 ID 直接表示两个表的关系；
资源的集合应支持过滤,排序和分页；
过滤、排序、分页应出现在参数列表中而不是Path中。
例如：GET /currencies?page=1&size=10
过滤条件应该合并到一个参数里：
        GET ://example/users?filter="name::todd|city::denver|title::grand poobah"
    排序字段也应该合并到一个参数里,使用-代表倒序
        GET ://example/users?sort=last_name|first_name|-hire_date
经常使用的、复杂的查询标签化,降低维护成本。
如：
GET /trades?status=closed&sort=createddesc

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。