22条助你提升API设计能力的好习惯？在这个微服务世界中，后端API的一致设计至关重要。今天，我们将讨论一些要遵循的最佳实践。我们将保持简短和甜蜜-所以系好安全带，让我们开始吧！首先是一些术语任何API设计都遵循一个叫做“面向资源的设计”的原则一个资源称为一个集合，例如：用户列表URL：标识一个资源或集合的位置，例如：/user1.使用kebab-case(破折号小写分隔形式）对于URL例如，如果您想要获取订单列表。不应该：/systemOrders或/system_orders应该：/system-orders2.参数使用驼峰命名法（CamelCase）例如，如果你想从特定商店购买产品。不应该是：/system-orders/{order_id}或/system-orders/{OrderId}应该是：/system-orders/{orderId}3.如果你想获得所有用户，则指向一个集合的复数名称系统。不应该：GET/user或GET/User应该：GET/users4.如果要保持概念的统一性和一致性，URL以集合开头，以标识符结尾。不应该是:GET/shops/:shopId/category/:categoryId/price这是不好的，因为它指向属性而不是资源。应该是：GET/shops/:shopId/或GET/category/:categoryId5.使动词远离你的资源URL不要在URL中使用动词来表达你的意图。相反，使用适当的HTTP方法来描述操作。不应该：POST/updateuser/{userId}或GET/getusers应该：PUT/user/{userId}6.对非资源URL使用动词如果您有一个仅返回操作的端点。在这种情况下，您可以使用动词。例如，如果您想向用户重新发送警报。应该：POST/alarm/245743/resend请记住，这些不是我们的CRUD操作。相反，它们被认为是在我们的系统中执行特定工作的功能。7.对JSON属性使用驼峰命名法。如果您正在构建请求主体或响应主体为JSON的系统，则属性名称应使用驼峰式而不是：{user_name:"MohammadFaisal"user_id:"1"}应为：{userName:"MohammadFaisal"userId:"1"}8.监控RESTfulHTTP服务必须实现/health和/version以及/metricsAPI端点。他们将提供以下信息。/health使用200OK状态代码响应对/health的请求。/version响应带有版本号的/version请求。/metrics端点将提供各种指标，例如平均响应时间。还强烈建议使用/debug和/status端点。9.不要使用table_name作为资源名称不要只使用表名作为资源名称。从长远来看，这种懒惰是有害的。不应该：product_order应该：product-orders这是因为暴露底层架构不是你的目的。10、使用API??设计工具写出好的文档有很多好的API设计工具，例如：APIBlueprintSwagger有很好的详细文档，可以给API用户带来良好的用户体验。11.对版本使用简单的序号始终对API使用版本控制并将它们移到左侧，以便它们具有最大的范围。版本号应为v1、v2等。应该：http://api.domain.com/v1/shops/3/products始终在您的API中使用版本控制，因为如果API被以下用户使用，更改端点可能会破坏其功能外部实体。12.在响应正文中包含资源总数如果API返回对象列表，请始终在响应中包含资源总数。您可以为此使用total属性。不应该：{users:[...]}应该：{users:[...],total:34}13.接受限制和偏移参数在GET操作中始终接受限制和偏移参数。应该是：GET/shops?offset=5&limit=5这是因为前端分页需要。14、get字段查询参数返回的数据量也要考虑在内。添加fields参数以仅公开API中需要的字段。示例：仅返回商店的名称、地址和联系方式。GET/shops?fields=id,name,address,contact在某些情况下它还有助于减少响应大小。15.不要在URL中传递authtoken这是一个非常糟糕的做法，因为url经常被记录并且authtoken被不必要地记录。不应该是：GET/shops/123?token=some_kind_of_authenticaiton_token相反，通过标头传递它们：Authorization:Bearerxxxxxx,Extrayyyyy此外，授权令牌应该是短暂的。16.验证内容类型服务器不应该假定内容类型。例如，如果您接受application/x-www-form-urlencoded，那么攻击者可以创建一个表单并触发一个简单的POST请求。因此，始终验证内容类型，如果要使用默认内容类型，请使用content-type:application/json17。将HTTP方法用于CRUD函数HTTP方法用于解释CRUD函数。GET：检索资源的表示。POST：创建新的资源和子资源。PUT：更新现有资源。PATCH：更新现有资源，它只更新提供的字段而不更新其他字段。DELETE：删除现有资源。18.在嵌套资源的URL中使用关系以下是一些实际示例：GET/shops/2/products：获取商店2中所有产品的列表。GET/shops/2/products/31：获取产品31的详细信息，属于商店2。DELETE/shops/2/products/31：应删除属于商店2的产品31。PUT/shops/2/products/31：应更新产品31的信息，仅在资源上使用PUT-URL，不是集合。POST/shops：应该创建一个新商店并返回创建的新商店的详细信息。在集合url上使用POST。19.CORS（跨源资源共享）必须支持所有面向公众的API的CORS（跨源资源共享）标头。考虑支持CORS允许的“*”来源并通过有效的OAuth令牌强制执行授权。避免将用户凭据与原始身份验证相结合。20.Secure在所有端点、资源和服务上强制执行HTTPS（tls加密）。强制并要求所有回调url、推送通知端点和webhook都使用HTTPS。21.错误当客户端向服务发出无效或不正确的请求，或者向服务传递无效或不正确的数据，而服务拒绝请求时，就会发生错误，或者更具体地说是服务错误。示例包括无效的身份验证凭据、不正确的参数、未知的版本ID等。当客户端请求由于一个或多个服务错误而被拒绝时，必须返回4xxHTTP错误代码。考虑处理所有属性并在单个响应中返回多个验证问题。22.黄金法则如果您对您的API格式决定有疑问，这些黄金法则可以帮助我们做出正确的决定。扁平比嵌套好。简单胜于复杂。字符串比数字好。一致性优于定制。就是这样-如果你已经走到这一步，恭喜你！希望你学到了一些东西。希望你今天过得愉快！译者：lzc先生，软件工程师，DevOpsDays，HDZ深圳核心组织者，目前就职于华为，从事云计算，专注于K8s和微服务。
