Season 1: 杂文
在 APILetter 的 S1E6，我想和你聊聊 OpenAPI 设计的重要性。 在整个 S1 的文章中，我用了接近 4 篇的篇幅来介绍 OpenAPI 的设计，从一开始介绍为什么要使用 RESTFul ，到 API 的错误码设计理念，辅以批量接口设计的实例，再加上最后这篇重要性的强调，三分之二的比重，意在让你深刻认识到，OpenAPI 的设计至关重要。 为什么 OpenAPI 的设计如此重要？ 在企业内部工作时，常常需要找到平衡质量和速度之间的折衷方案。当项目时间非常紧迫时，往往会牺牲一些质量。但如果项目有足够的时间，就有更高的概率能够设计出一个质量更好、开发者体验更佳的 OpenAPI。 然而，OpenAPI 是一项非常重要的任务，不能马马虎虎。一个坏的设计会让团队持续在 OpenAPI 开发上投入更多的精力。 沟通难度高带来的维护成本增高问题 和企业团队内部使用的 API 不同，OpenAPI 的用户是外部团队，
Season 1: 杂文
许久不见，甚是想念，最近做了不少 RESTFul API 的设计实践，分享一下最新的经验。 在遵循 RESTFul 风格设计 OpenAPI 时，简单的创建、更新、查询、删除是比较好做的，大家也大多能够想到如何设计对应的接口，无非是用 POST 做创建、GET 做查询、DELETE 做删除、PUT、PATCH 做更新，但设计到批量的操作时，大家往往会有一些困惑，今天我们就来聊聊 RESTFul 下的批量操作。在给出我自己具体的实践之前，先来看看业界的实践。 业界的两种实践 由于 RESTFul 风格定义当中并没有明确说明如何设计批量接口，所以业界上也有不同的批量接口设计的思路，大体可以分为两种： 1. 在网关层面设计批量接口的能力，实现异步转同步：这部分主要是会提供一个单独的请求路径，由开发者将自己的请求打包并发送到这个新的路径，由这个路径上的服务将请求结果发送给具体的服务，并将结果收回，返回给开发者。Google 和
Season 1: 杂文
在对外开放 OpenAPI 的时候，错误的设计也是一个极为影响开发者开发体验的设计点。今天我们简单聊聊关于错误码和错误处理 为什么需要错误码？ 由于我们不能保证系统可以完全处理用户的请求，因此我们需要通过错误码来告诉开发者发生了不符合预期的情况。不符合预期的情况可能由用户输入错误导致，也可能由内部微服务故障导致。为了建设一个健壮（Robust）的系统，我们需要通过对外暴露一批错误码，帮助开发者更好地处理各种异常情况。 避免错误码数量过少 既然我们的目的是帮助开发者解决异常情况，那么一个合理的答案是：和异常情况匹配的错误码数量是一个好的错误码数量。 如果在某个 API 接口上提供了一个错误码，则意味着我们认为这个接口只会出现一种情况导致的错误。而实际上，很可能会有多种情况导致错误发生。这种情况经常在 OpenAPI 评审过程中被提出来，也是用户在使用 OpenAPI 时常遇到的问题：为什么我找不到这个错误码？对于开发者来说，无论输入何种错误，都会得到相同的错误码，难以定位和解决问题。同一个错误码也意味着你无法提供足够的错误信息来进行排查。例如，常见的 “400 Bad Re