【编辑推荐】在设计REST API时是否感到困惑？ 请不要担心，以下是一些建设REST API的非常实用的建议！你是否因为一个糟糕的API而感到过沮丧？在微服务的环境中，保证后端API的一致性设计是非常重要的。今天，我们要谈一些可以遵循的最佳做法。我们会尽量让话语简洁而有情调- 所以请系好安全带，我们出发吧！
[[424906]]
首先，让我们介绍一些术语在任何API设计中都遵循一种叫做"面向资源设计"的原则
资源：资源是数据的一部分，例如：用户 集合：一组资源称为集合，例如：用户列表 URL：用于标识资源或集合的位置，例如：/用户 1. 使用kebab-case(短横线小写隔开形式)来命名URL比如，如果你希望获取订单列表。
的命名不应该使用/
或/
_orders，而应该使用/
/system-orders
2。参数应该使用驼峰形式，例如，如果你想要从一个特定的商店购买产品。不应该是使用/system-orders/{order_id}或/system-orders/{OrderId}
应该是使用/system-orders/{orderId}
3。指向集合的复数名称如果你想获取系统中的所有用户。
应该避免:
使用 /user或 /User
应该选择:
使用 /users
4. URL应该以集合来表示，以标识符来结束这样可以保持概念的单一性和统一性。
不应该使用 /商店/:店铺ID/分类/:分类ID/价格
这是不好的，因为它指向的是一个属性，而不是资源。
应当:
获取 /商店/:店铺ID/或获取 /类别/:类别ID
5. 避免在资源URL中使用动词不要在URL中使用动词来表达意图。反之，应当使用正确的HTTP方法来指定操作。
不应该：使用POST请求来更新用户信息或使用GET请求来获取用户信息。应该：使用PUT请求来更新用户信息
6. 对于非资源URL，应该使用动词来表示操作，比如如果你有一个端点，它只返回一个操作。在这种情形下，您可使用动作词。比如说，如果你需要再次向用户发送警报。
应该是:
发送 /alarm/245743/重新发送
请注意，这些不是我们的CRUD操作。相反，它们被认为是执行系统中特定工作的功能。
如果你在构建一个JSON请求或响应体的系统，应该使用驼峰式命名JSON属性名。那么命名属性时应该采用驼峰大小写
，而不应该采用： BOB半岛官方
{ user_name: "Mohammad Faisal" user_id: "1" }
应该：
{ userName: "Mohammad Faisal" userId: "1" }
8. 监控RESTful HTTP服务必须实现/health和/version和/metricsAPI端点。他们将提供如下资讯。他们会在接收到/health请求时，使用200 OK状态码作出响应，并提供以下信息：
/health
。使用版本号对请求/version进行响应。BOB半岛下载
/metrics
的端点将提供多种指标，比如平均响应时间。建议强烈推荐使用/debug和/status端点。
9. 请勿将表名作为资源名请勿仅使用表名作为资源名称。就长远而言，这种懒散是有害的。
不应该：product_order
应该是：product-orders
，因为公开底层体系结构不符合你的目的。
1. 使用API设计工具有许多好处。有许多优秀的API设计工具可用于编写文档，比如： - API蓝图 - Swagger详细而完善的文档能为API使用者提供很好的用户体验。11. 始终对API使用版本控制，使用简单的序数作为版本，并将其向左移，以确保具有最大的作用范围。应该使用 v1、v2 等版本号。
需要确保：
http://api.domain.com/v1/shops/3/products应始终在API中使用版本控制，因为如果API被外部实体使用，更改端点可能会破坏它们的功能。12. 如果API返回一个对象列表，在您的响应体中请包括资源的总数
的不适宜做法：
{ 用户: [ ... ] }
应该的做法：
{ 用户: [ ... ], 总数: 34 }
13. 在进行GET操作时，应该始终接受limit和offset参数
。应该将BOB半岛首页
修改为获取，以便更加准确地表达需要GET的操作。具体来说，应该使用以下URL： /shops？offset=5&limit=5
这是因为它对于前端分页非常重要。
14. 应该将获取字段查询参数
返回的数据量一并考虑。请增加一个fields参数，仅暴露API中所需的字段。示例：
仅提供商店的名称、地址和联系电话。
获取 /商店？在一些情况下，这也有助于减少响应的大小。
15. 不应该将认证令牌放在URL中传输。这是一种非常糟糕的做法，因为URL通常被记录，同时也会不必要地记录身份验证令牌。不应该这样写：
使用 /shops/123请求{GET}方法。token=一种身份验证令牌
相反，可以通过头部传递它们：
Authorization: Bearer xxxxxx, Extra yyyyy BOB半岛老版本
此外，授权令牌应该有限的有效期。16. 服务器不应该假定内容类型，应该验证内容类型。比如说，假如您允许接受application/x-www-form-urlencoded 格式的请求，那么攻击者可以制作一个表单并发送一个简单的POST请求来触发攻击。由于如此，一直要验证内容类型，如果想要使用默认的内容类型，请使用 content-type: application/json。\n17. 对于CRUD功能，要使用HTTP方法。\nHTTP方法用于解释CRUD功能。使用GET方法：检索资源的表示形式。 POST：用于创建新资源和子资源。 PUT方法用于更新已存在的资源。 PATCH：对现有资源进行更新，只会更新提供的字段，不会更新其他字段。DELETE：用于删除已存在的资源。 18. 使用关联的方式在嵌套资源的URL中
，下面是一些示例:
GET /shops/2/products：获取商店2的所有产品列表。
请求方式：GET\n请求URL：/shops/2/products/31\n功能：获取产品31的详细信息，该产品属于商店2。删除请求：DELETE /shops/2/products/31，旨在删除商店2中的产品31。
应该使用PUT方法仅针对资源URL而非集合，以更新商品31的信息。
请求POST /shops用于创建新商店，并返回新商店的详细信息。使用POST方法发送请求到URL集合。19. 对于所有开放公共API，必须支持CORS（跨源资源共享）头部。考虑支持CORS并允许所有来源的请求，并通过有效的OAuth令牌进行授权验证。避免将用户凭证和原始验证方式联合使用BOB半岛平台。所有端点、资源和服务都需要实施HTTPS（TLS加密）以确保安全。所有回调URL、推送通知端点和webhooks必须使用HTTPS，且必须强制执行。
21. 发生错误的情况
通常是由于客户端向服务端发起的请求不完整或不正确，或者服务端接收到的数据无效或不正确。当服务端判定无法处理该请求时，便会产生错误，具体表现为服务错误。诸如无效的身份验证凭证、参数错误、未知的版本id等情况都可作为例子。当客户端请求被拒绝时，应该返回4xx HTTP错误代码，这通常是由于一个或多个服务错误引起的。 考虑对所有属性进行处理，以便在单个响应中返回多个验证问题。22. 若您对API格式的决定感到迷惑，这些黄金准则可指导我们做出正确的决策。扁平比嵌套更佳。简洁胜于繁琐。使用字符比数字更好。 一致性比定制更佳。
就是这样——如果你已经达到了这一点，祝贺你！希望你已经收获了一些新的知识。希望你今天过得愉快！翻译者：Mr.lzc，是一位软件工程师，也是DevOpsDays和HDZ深圳核心组织者，目前在华为就职，专注于云计算工作，主攻K8s和微服务领域。
BOB半岛入口
BOB半岛下载
