深圳网站制作电话,360 网站优化,汕头网站排名优化,临海网站设计最近团队人数在扩大#xff0c;才发现#xff0c;REST 这个出来很多年头的东西#xff0c;居然还有人用不好。说起来#xff0c;REST 出现已经很久了。从早期的三层架构#xff0c;到现在的多层、微服务#xff0c;核心内容之一就是 API --- 从非常简单的 API#xff0c… 最近团队人数在扩大才发现REST 这个出来很多年头的东西居然还有人用不好。说起来REST 出现已经很久了。从早期的三层架构到现在的多层、微服务核心内容之一就是 API --- 从非常简单的 API到多设备多用途的 API包括一些外接的三方像 BAT 的公共服务简单的、麻烦的都是 API。而这些 API又基本上都是基于 REST 的。今天我们不去详细解释 REST只说说 REST 应用中间的一些要点。REST 应用之多是有他的原因的。他很容易理解很灵活并且可以适用于任何规模的应用。当然REST 并不是唯一的规范还有 SOAP、GraphQL。但是这只是字面上的并列的规范。所有的规范用过了你就会知道SOAP 很笨重有时候还很古怪你需要花大量的心思去想接口的表示而不是逻辑本身。至于 GraphQL又延伸的太多了居然需要调用 API 的客户端去考虑和设计这绝不是个好主意。好吧这个问题见仁见智我们不展开讨论。不管怎么说在我看来REST 仍然是 API 接口规范的王者并且不会在短时间内被取代。在我的习惯中使用 REST 会有以下几个约束。1. 使用 JSON 数据别误解这是我的习惯不是 REST 的。REST 并没有规定使用什么样的格式来传递数据XML 也行JSON 也行。但是在我的团队中JSON 传递数据是一个硬性要求。相比较而言JSON 比 XML 有太多的优势了更易于使用、书写和阅读更快占用的内存空间更少不需要特殊的依赖项或包来解析主流的编程语言对 JSON 都有支持如果不理解这些优势没关系去网上随便找一个 XML试着自己解析一下看看。熟悉大厂的各种开放平台的同学们也会有直觉的感觉早期的 SOAP 和 XML已经被逐步替换为了 REST 和 JSON。此外这里说的使用 JSON 数据不仅仅是响应数据还包括请求数据。不要使用 form-data 或者 x-www-form-urlencoded 发送数据转成 JSON 发送会更容易阅读、编写、测试和管理。真心的如果你这么做了我会替所有开发的同学们感谢你。2. 认真对待方法想一下你有没有见到过只用 GET 方法来处理一切事情的 API这并不是不可以只不过这样的写法说明没有深入理解这个工具以及 HTTP 的准确的工作方式。要知道HTTP 中每个方法都被设计为处理特定的工作和内容。这儿我逐个说说GET - 在仅仅用于读数据时应该用 GET。不写入、不更新只读取数据。这个概念很简单。而且在这个前提下相同的请求一定会返回相同的结果。POST - 看字面的意思就明白就是存储一些东西像是在数据库中创建一条记录、在某处写入一些内容。通常来说可以选择很多种方式 POST 数据multipart/form-data、x-www-form-urlencoded、application/json 或者 text/plain等等很多。不过我们要求只使用 application/json 方式这样做可以保持开发和调用的一致性。PUT - 字意就是更新内容。所以当我们需要更新数据时就需要定义为 PUT 方法。当然也可以用来创建新数据。DELETE - 删除很好理解。PATCH - 打补丁对于已经存在的数据进行更新操作。这个跟 PUT 有一点点区别通常 PATCH 是有范围的更新需要更新的内容而 PUT 更多时候是更新整个数据。当然在某些文章里还会有 OPTIONS、HEAD、TRACE等等这些用得少就不说了。想了解的可以去查 HTTP 相关的文档。说这么多重要的是 --- 既然 HTTP 提供了这样的方法定义我们完全可以把任何 CRUD 的操作对映到这些方法而不是只用 GET这决不是一个好习惯。3. 注意语义在团队开发 API 时有一个严格的要求就是 API 名称需要有语义感。语义感这个词是我自己生造的不是什么高大上的东西就是要求写的 API 名称能使用正确的英文和次序能够让人看得懂。都 9021 年了居然还有人用拼音首字符说出来你敢信吗在我看来所有的 API 都应该可以在不看注释和说明的情况下被调用方理解从调用端点到参数和 JSON 的键。这儿我参考了国外的一些规则。规则也很简单用名词别用动词。想一下上面列出的方法本身就是动词比方说GET /clients就很好理解如果换成 GET /getClients总觉得怪怪的。一定要准确使用单数和复数针对一条数据就用单数针对多条数据就一定用复数。感觉一下 GET /client 和 GET /clients 的区别。当然对于单个数据来说通常还需要某种 ID 的存在GET /client/id。下面用一些例子来理解一下这个规则。// 好的方式
GET /clients
POST /clients
GET /client/23
PUT /client/23
DELETE /client/23
GET /client/23/comments// 不好的方式
GET /clients/23
GET /listAllClients
POST /client/create
PUT /updateClient/23
GET /clientComments/23这儿要多说两句规则只是规则不用那么死板的去记。要把这种规则理解了并习惯性地应用在编程的过程中变成一种类似肌肉记忆的东西。4. 随时留心 API 的安全就算你做得不是公开的 API也一定要记着使用某些手段让你的 API 安全起来。这是 API 编程一个基本的要求。这又有几个方面的要求1. 使用 HTTPsHTTPs 已经出来非常久了而且如果你对接过大厂的 API你会发现使用 HTTPs 是一个基本的要求。HTTPs 提供了一种比 HTTP 更安全的方式可以在基本网络层面除去中间人攻击并加密调用端和 API 的通讯。在编程时使用 HTTPs 是个成本最低但又确实有效的安全方式。把使用 HTTPs 当成一个标准和习惯有一天你会感谢自己的。2. 从构建 API 开始就要做到控制访问你看得没错是从构建 API 开始。不需要做得很麻烦但要有控制要能控制谁能访问这个 API。通常可以先加入一个简单的 JWT Auth等 API 成形后再转为 OAuth。目的很简单就是控制访问。如果真出现了 API 被攻击什么的简单地关闭暴露的密钥就可以了。当然我们还可以用密钥来跟踪 API 的调用包括调用量、调用异常等。3. 小心对待敏感数据API 代表了网络代表了通讯。在网络和通讯上传递敏感数据一定要小心再小心。我们前边提到了一定使用 HTTPs也是因为这个。如果不想面向监狱编程一定要确保这些敏感数据通过正确的方式给到正确的调用方。看了一眼数据就被追了刑责这是我身边的真事。4. 确保运行环境的安全网关、防火墙有就用上别因为麻烦就关掉。更深的内容可以扔给运维但基础的部分自己要懂要会。5. 版本控制API 叠代升级是每个开发的会面对的事。有时候升级仅仅是逻辑的改变而更多时候是会改变输入输出结构的。这种情况下保持和维护 API 的版本很重要。作为后端开发人员我们无法保证调用端会随时同步进行相应的改动。极端情况下改变内部逻辑也有可能影响到调用端。API 版本控制不用犹豫马上开始使用。不要觉得某个 API 比较小或者调用端少就不去做。记着任何的代码改动对于不更新应用或其它内容的调用者来说都是有风险的。你不仅需要确保你的代码不会破坏任何东西或任何人还需要知道某个应用版本的表现。这件事一点都不好玩。关于 API 版本控制的详细实现我前边一篇推文可以去看看。传送门至于版本的方式倒是不那么重要可以看个人的习惯v1、v2、v3也可以v1.0、v1.1、v1.2也可以。按照微软的建议是采用 Major.Minor.Patch 的方式。不过我自己觉得带上 Patch 部分有点太长了。所以在我的习惯中应用版本控制后API 的 URL会是这样的GET /v1.7/clients
POST /v1.7/clients
GET /v1.7/client/23
PUT /v1.7/client/23
DELETE /v1.7/client/23
GET /v1.7/client/23/comments听我的马上开始 API 的版本控制。6. 保持响应的一致一致性是好的 API 的优秀品质。开发中我们应该在各种方面做到一致包括命名、URI、请求、响应等。而在这里面响应的一致性是我对团人的一个硬性要求。API 是要让别人去调用的。保持资源响应的一致是对调用者最大的善意。在某个坛子上我看到过建议每个端点返回不同资源结构的说法。如果你也看到过类似的内容忘了它那是错的。记着这句话保持资源响应的一致是对调用者最大的善意。API 开发时尽可能发送相同的响应结构。如果没有数据就将其作为空值、空对象或空数据发送。我们拿论坛的文章结构举个例子。文章数据的结构通常是这样有简化不要纠结{title: 文章标题,description: 文章内容,comments:[{text: 回复1,user: 张三},{text: 回复1,user: 张三}]
}如果需要返回一条数据并且要列出评论时结果会是这样{message: fetch data successed,status: true,article:{title: 文章标题,description: 文章内容,comments:[{text: 回复1,user: 张三},{text: 回复1,user: 张三}]}
}如果需要返回一个文章列表并且没有评论时会是这样{message: fetch data successed,status: true,articles:[{title: 文章标题1,description: 文章内容1,comments: []},{title: 文章标题2,description: 文章内容2,comments: []}]
}看到了吧这样的方式下我们对于里面元素 article 里结构是完全一样的而对于整个返回结构也是相似的。坚持这样做可以为自己和他人节省大量的时间。7. 重视出错后的返回信息API 开发应该既能处理正确的请求也能处理错误的请求。错误的请求并不可怕可怕的是你没有考虑到或者考虑到了但没有给到调用端足够的细节。在 API 返回中很多人在这里会忽略 HTTP 的状态代码也就是 HttpStatus。HTTP 协议为我们定义了超过 50 种不同的状态代码涵盖了几乎所有的场景。每个代码都有独特的含义应该在独特的场景中使用。这个内容网上有很多我就简单列一下1xx - 信息性响应代码简单说就是一个状态通知。2xx - 成功响应代码。所有的成功都会在这个范围。通常我们见到的是 200但也有别的成功情况。3xx - 重定向响应代码。请求被服务器重定向到另一个 URL就会有这个返回。4xx - 客户端错误响应代码。最常见的是 400请求协议格式或内容错误。5xx - 服务器错误响应。最常见的是 500服务端程序也就是 API 的内部有内存溢出或异常抛出。开发中我们可以充分并准确使用这些状态码。这样所有的开发人员会在相同的认识层次上理解问题的状态和原因从而使得 API 变得普遍易懂、一致和标准。这不是 REST 的标准但应该作为我们开发 REST 的标准。有了状态码这只是第一步。当运行出错时我们需要向调用端提供尽可能多的细节。当然这并不容易我们需要能够考虑并预测 API 会如何出错调用者会做什么不会做什么。所以通常一个 API 第一步是进行严格的请求数据验证数据是否存在、值是否在我们期望的范围内、是否可以将他们存入数据库。拿上面的例子来说GET /client/23取 clientId 23 的数据我们需要做以下的工作检查请求是否有 clientId 参数如果没有应该是一个 400 的状态检查传入的 clientId 23 的记录是否存在如果不存在返回响应 404如果找到记录则返回响应 200这只是一个简单的例子真实的编程时需要考虑的会更多。而且除了状态码外还要返回相应的错误消息例如输入参数 clientId 没有输入、ID 为 23 的数据记录不存在等等。重要的是提供详细的错误信息可以帮助开发者和调用方了解到底什么地方发生了问题。放心调用者不会将这些信息显示给最终用户但可以通过这些信息来快速的定位和解决问题。8. 尽可能优化在现代编程中API 在体系中的角色绝对是整个操作的大脑。所以对于 API 的开发最基本的要求是快速和优化决不能让 API 成为整个系统和生态的痛点。要求就这么简单。我们可以做很多事情来确保交付一个具备良好性能和可伸缩性的 API。来看看我们能做什么首先是数据库级别的优化。通常说 API 慢的时候十有八九与数据库有关。糟糕的数据库设计、复杂的查询、缓慢的硬件环境甚至缺乏缓存都是慢的理由。所以开发过程中应该随时关注并始终优化数据库结构、查询、索引以及与数据库交互的所有内容。接下来是缓存。很多人不愿意用缓存因为会将代码变复杂。但是从实际效果上越大、越复杂的系统越应该通过缓存传递数据。有时候缓存数据库查询能减少 100% 的加载时间。而绝大多数数据不会进行频繁的改变。把缓存用起来调用端的兄弟们会把你当亲兄弟的。另一个影响性能的因素是 API 发送到调用端的数据量。要做到确保 API 只返回调用端需要的数据而不是全部。如果可能不要每次都返回完整的模型细节和关系。试一下但要与响应中的返回模型保持一致。最后别忘了压缩。如果可以使用 Brotli或者至少也使用 Gzip 来压缩数据。简单的配置可以获得减少 50-75% 的传输数据多好9. 做个体贴的开发者这个要求无关技术但我还是想写出来。作为一个开发人员我们要明白项目不是一个人的事。当我们写完最后一行代码提交并合并后你可能会认为工作已经完成。但不是对其他很多人来说这才是个刚刚开始。很多人在我们完成了工作后才能开始他们的工作。所以我们需要以多种方式准备 API。我们要确保 API 能正常工作要有很好的文档更重要的事我们需要准备好集成支持。不过文档写得有多好在集成过程中及以后的过程中总会有问题各种问题。所以设身处地的为他人着想尽量让他们的工作变得容易些。构建一个良好的API遵循我们在这里定义的规则编写优秀的文档并为所有人服务。10. 写完了写完了。上面九条是我团队中执行的标准和要求。这里我也必须说 REST 本身并不是一个标准所以也不会有人告诉你什么是对的什么是错的。开发的时候多想一下作为开发人员我们每天都在寻找使代码更好、更漂亮、更高效的模式那么为什么不在 API 中也做同样的事呢全文完。喜欢就来个三连让更多人因你而受益
