在这个微服务的世界里，后端API的一致性设计是必不可少的。

明天，咱们将探讨一些可遵循的最佳实际。咱们将放弃简短和苦涩——所以系好安全带，登程咯！

首先介绍一些术语

任何API设计都遵循一种叫做“面向资源设计”的准则：

  • 资源：资源是数据的一部分，例如：用户
  • 汇合：一组资源称为汇合，例如：用户列表
  • URL：标识资源或汇合的地位，例如：/user

1. 对URL应用kebab-case（短横线小写隔开模式）

例如，如果你想要取得订单列表。

不应该：

/systemOrders或/system_orders

应该：

/system-orders

2. 参数应用camelCase（驼峰模式）

例如，如果你想从一个特定的商店购买产品。

不应该：

/system-orders/{order_id}

或者：

/system-orders/{OrderId}

应该：

/system-orders/{orderId}

3. 指向汇合的复数名称

如果你想取得零碎的所有用户。

不应该：

GET /user

或：

GET /User

应该：

GET /users

4. URL以汇合开始，以标识符完结

如果要放弃概念的单一性和一致性。

不应该：

GET /shops/:shopId/category/:categoryId/price

这很蹩脚，因为它指向的是一个属性而不是资源。

应该：

GET /shops/:shopId/或GET /category/:categoryId

5. 让动词远离你的资源URL

不要在URL中应用动词来表白你的用意。相同，应用适当的HTTP办法来形容操作。

不应该：

POST /updateuser/{userId}

或：

GET /getusers

应该：

PUT /user/{userId}

6. 对非资源URL应用动词

如果你有一个端点，它只返回一个操作。在这种状况下，你能够应用动词。例如，如果你想要向用户从新发送警报。

应该：

POST /alarm/245743/resend

请记住，这些不是咱们的CRUD操作。相同，它们被认为是在咱们的零碎中执行特定工作的函数。

7. JSON属性应用camelCase驼峰模式

如果你正在构建一个申请体或响应体为JSON的零碎，那么属性名应该应用驼峰大小写。

不应该：

{   user_name: "Mohammad Faisal"   user_id: "1"}

应该：

{   userName: "Mohammad Faisal"   userId: "1"}

8. 监控

RESTful HTTP服务必须实现/health和/version和/metricsAPI端点。他们将提供以下信息。

/health

用200 OK状态码响应对/health的申请。

/version

用版本号响应对/version的申请。

/metrics

这个端点将提供各种指标，如均匀响应工夫。

也强烈推荐应用/debug和/status端点。

9. 不要应用table_name作为资源名

不要只应用表名作为资源名。从久远来看，这种懈怠是无害的。

不应该：

product_order

应该：

product-orders

这是因为公开底层体系结构不是你的目标。

10. 应用API设计工具

有许多好的API设计工具用于编写好的文档，例如：

  • API蓝图：https://apiblueprint.org/
  • Swagger：https://swagger.io/

领有良好而具体的文档能够为API使用者带来良好的用户体验。

11. 应用简略序数作为版本

始终对API应用版本控制，并将其向左挪动，使其具备最大的作用域。版本号应该是v1，v2等等。

应该：http://api.domain.com/v1/shop...

始终在API中应用版本控制，因为如果API被内部实体应用，更改端点可能会毁坏它们的性能。

12. 在你的响应体中包含总资源数

如果API返回一个对象列表，则响应中总是蕴含资源的总数。你能够为此应用total属性。

不应该：

{  users: [     ...  ]}

应该：

{  users: [     ...  ],  total: 34}

13. 承受limit和offset参数

在GET操作中始终承受limit和offset参数。

应该：

GET /shops?offset=5&limit=5

这是因为它对于前端的分页是必要的。

14. 获取字段查问参数

返回的数据量也应该思考在内。增加一个fields参数，只公开API中必须的字段。

例子：

只返回商店的名称，地址和联系方式。

GET /shops?fields=id,name,address,contact

在某些状况下，它还有助于缩小响应大小。

15. 不要在URL中通过认证令牌

这是一种十分蹩脚的做法，因为url常常被记录，而身份验证令牌也会被不必要地记录。

不应该：

GET /shops/123?token=some_kind_of_authenticaiton_token

相同，通过头部传递它们：

Authorization: Bearer xxxxxx, Extra yyyyy

此外，受权令牌应该是短暂有效期的。

16. 验证内容类型

服务器不应该假设内容类型。例如，如果你承受application/x-www-form-urlencoded，那么攻击者能够创立一个表单并触发一个简略的POST申请。

因而，始终验证内容类型，如果你想应用默认的内容类型，请应用：

content-type: application/json

17. 对CRUD函数应用HTTP办法

HTTP办法用于解释CRUD性能。

GET：检索资源的示意模式。

POST：创立新的资源和子资源。

PUT：更新现有资源。

PATCH：更新现有资源，它只更新提供的字段，而不更新其余字段。

DELETE：删除已存在的资源。

18. 在嵌套资源的URL中应用关系

以下是一些理论例子：

  • GET /shops/2/products：从shop 2获取所有产品的列表。
  • GET /shops/2/products/31：获取产品31的详细信息，产品31属于shop 2。
  • DELETE /shops/2/products/31：应该删除产品31，它属于商店2。
  • PUT /shops/2/products/31：应该更新产品31的信息，只在resource-URL上应用PUT，而不是汇合。
  • POST /shops：应该创立一个新的商店，并返回创立的新商店的详细信息。在汇合url上应用POST。

19. CORS（跨源资源共享）

肯定要为所有面向公共的API反对CORS（跨源资源共享）头部。

思考反对CORS容许的“*”起源，并通过无效的OAuth令牌强制受权。

防止将用户凭证与原始验证相结合。

20. 平安

在所有端点、资源和服务上施行HTTPS（tls加密）。

强制并要求所有回调url、推送告诉端点和webhooks应用HTTPS。

21. 谬误

当客户端向服务收回有效或不正确的申请，或向服务传递有效或不正确的数据，而服务回绝该申请时，就会呈现谬误，或者更具体地说，呈现服务谬误。

例子包含有效的身份验证凭证、不正确的参数、未知的版本id等。

  • 当因为一个或多个服务谬误而回绝客户端申请时，肯定要返回4xx HTTP错误代码。
  • 思考解决所有属性，而后在单个响应中返回多个验证问题。

22. 黄金法令

如果您对API格局的决定有疑难，这些黄金规定能够帮忙咱们做出正确的决定。

  • 扁平比嵌套好。
  • 简略胜于简单。
  • 字符串比数字好。
  • 一致性比定制更好。

就是这样——如果你曾经走到了这一步，祝贺你！心愿你学到了一些货色。

起源：dockone.io/article/2434604

链接：betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9

译者：刘志超，软件工程师、DevOpsDays、HDZ深圳外围组织者，目前供职于华为，从事云计算工作，专一于K8s、微服务畛域。

近期热文举荐：

1.1,000+ 道 Java面试题及答案整顿(2022最新版)

2.劲爆！Java 协程要来了。。。

3.Spring Boot 2.x 教程，太全了！

4.别再写满屏的爆爆爆炸类了，试试装璜器模式，这才是优雅的形式！！

5.《Java开发手册（嵩山版）》最新公布，速速下载！

感觉不错，别忘了顺手点赞+转发哦！