22条API设计的最佳实践
管她前浪，还是后浪？
能浪的浪，才是好浪！
每天 10:33 更新文章，每天掉亿点点头发...
源码精品专栏
曾经因为一个糟糕的API而感到沮丧吗？
在这个微服务的世界里，后端API的一致性设计是必不可少的。
今天，我们将讨论一些可遵循的最佳实践。我们将保持简短和甜蜜——所以系好安全带，出发咯！
首先介绍一些术语
任何API设计都遵循一种叫做“面向资源设计”的原则：
-
资源：资源是数据的一部分，例如：用户 -
集合：一组资源称为集合，例如：用户列表 -
URL：标识资源或集合的位置，例如：/user
例如，如果你想要获得订单列表。
不应该：
/systemOrders或/system_orders
应该：
/system-orders
基于 Spring Boot + MyBatis Plus + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能。
例如，如果你想从一个特定的商店购买产品。
不应该：
/system-orders/{order_id}
或者：
/system-orders/{OrderId}
应该：
/system-orders/{orderId}
基于微服务的思想，构建在 B2C 电商场景下的项目实战。核心技术栈，是 Spring Boot + Dubbo 。未来，会重构成 Spring Cloud Alibaba 。
如果你想获得系统的所有用户。
不应该：
GET /user
或：
GET /User
应该：
GET /users
如果要保持概念的单一性和一致性。
不应该：
GET /shops/:shopId/category/:categoryId/price
这很糟糕，因为它指向的是一个属性而不是资源。
应该：
GET /shops/:shopId/或GET /category/:categoryId
不要在URL中使用动词来表达你的意图。相反，使用适当的HTTP方法来描述操作。
不应该：
POST /updateuser/{userId}
或：
GET /getusers
应该：
PUT /user/{userId}
如果你有一个端点，它只返回一个操作。在这种情况下，你可以使用动词。例如，如果你想要向用户重新发送警报。
应该：
POST /alarm/245743/resend
请记住，这些不是我们的CRUD操作。相反，它们被认为是在我们的系统中执行特定工作的函数。
如果你正在构建一个请求体或响应体为JSON的系统，那么属性名应该使用驼峰大小写。
不应该：
{
user_name: "Mohammad Faisal"
user_id: "1"
}
应该：
{
userName: "Mohammad Faisal"
userId: "1"
}
RESTful HTTP服务必须实现/health和/version和/metricsAPI端点。他们将提供以下信息。
/health
用200 OK状态码响应对/health的请求。
/version
用版本号响应对/version的请求。
/metrics
这个端点将提供各种指标，如平均响应时间。
也强烈推荐使用/debug和/status端点。
不要只使用表名作为资源名。从长远来看，这种懒惰是有害的。
不应该：
product_order
应该：
product-orders
这是因为公开底层体系结构不是你的目的。
有许多好的API设计工具用于编写好的文档，例如：
-
API蓝图：https://apiblueprint.org/ -
Swagger：https://swagger.io/
拥有良好而详细的文档可以为API使用者带来良好的用户体验。
始终对API使用版本控制，并将其向左移动，使其具有最大的作用域。版本号应该是v1，v2等等。
应该：http://api.domain.com/v1/shops/3/products
始终在API中使用版本控制，因为如果API被外部实体使用，更改端点可能会破坏它们的功能。
如果API返回一个对象列表，则响应中总是包含资源的总数。你可以为此使用total属性。
不应该：
{
users: [
...
]
}
应该：
{
users: [
...
],
total: 34
}
在GET操作中始终接受limit和offset参数。
应该：
GET /shops?offset=5&limit=5
这是因为它对于前端的分页是必要的。
返回的数据量也应该考虑在内。添加一个fields参数，只公开API中必需的字段。
例子：
GET /shops?fields=id,name,address,contact
在某些情况下，它还有助于减少响应大小。
这是一种非常糟糕的做法，因为url经常被记录，而身份验证令牌也会被不必要地记录。
不应该：
GET /shops/123?token=some_kind_of_authenticaiton_token
相反，通过头部传递它们：
Authorization: Bearer xxxxxx, Extra yyyyy
此外，授权令牌应该是短暂有效期的。
服务器不应该假定内容类型。例如，如果你接受application/x-www-form-urlencoded，那么攻击者可以创建一个表单并触发一个简单的POST请求。
因此，始终验证内容类型，如果你想使用默认的内容类型，请使用：
content-type: application/json
HTTP方法用于解释CRUD功能。
GET：检索资源的表示形式。
POST：创建新的资源和子资源。
PUT：更新现有资源。
PATCH：更新现有资源，它只更新提供的字段，而不更新其他字段。
DELETE：删除已存在的资源。
以下是一些实际例子：
-
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。
一定要为所有面向公共的API支持CORS（跨源资源共享）头部。
考虑支持CORS允许的“*”来源，并通过有效的OAuth令牌强制授权。
避免将用户凭证与原始验证相结合。
在所有端点、资源和服务上实施HTTPS（tls加密）。
强制并要求所有回调url、推送通知端点和webhooks使用HTTPS。
当客户端向服务发出无效或不正确的请求，或向服务传递无效或不正确的数据，而服务拒绝该请求时，就会出现错误，或者更具体地说，出现服务错误。
例子包括无效的身份验证凭证、不正确的参数、未知的版本id等。
-
当由于一个或多个服务错误而拒绝客户端请求时，一定要返回4xx HTTP错误代码。 -
考虑处理所有属性，然后在单个响应中返回多个验证问题。
如果您对API格式的决定有疑问，这些黄金规则可以帮助我们做出正确的决定。
-
扁平比嵌套好。 -
简单胜于复杂。 -
字符串比数字好。 -
一致性比定制更好。
就是这样——如果你已经走到了这一步，恭喜你！希望你学到了一些东西。
希望你度过美好的一天！
译者：Mr.lzc，软件工程师、DevOpsDays、HDZ深圳核心组织者，目前供职于华为，从事云计算工作，专注于K8s、微服务领域。
原文：https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9
已在知识星球更新源码解析如下：
最近更新《芋道 SpringBoot 2.X 入门》系列，已经 101 余篇，覆盖了 MyBatis、Redis、MongoDB、ES、分库分表、读写分离、SpringMVC、Webflux、权限、WebSocket、Dubbo、RabbitMQ、RocketMQ、Kafka、性能测试等等内容。
提供近 3W 行代码的 SpringBoot 示例，以及超 4W 行代码的电商微服务项目。
文章有帮助的话，在看，转发吧。
谢谢支持哟 (*^__^*）