API设计优先与代码优先的比较 - 让你满意的API

## 代码优先与文档的关系

在代码优先的开发模式中，开发者通常会先编写大量代码并部署系统，让客户直接接入使用。然而，这种方法常常伴随着一个常见的借口：“我们稍后再写文档”。实际上，这种说法往往意味着“我们根本不会写文档”。

这种开发方式的问题在于，缺乏清晰的文档会导致后续的维护和扩展变得困难。用例驱动开发虽然可以帮助快速实现功能，但如果没有文档的支持，团队协作和客户使用都会受到影响。

---

## 代码优先并添加注解

![](https://explinks-blog.oss-cn-beijing.aliyuncs.com/md/2025/08/47c175b43cfadbb35bad632070a90c6b.png)

代码优先的方法中，另一种改进方式是通过注解为API添加文档信息。这种方法在强类型语言中表现较好，因为许多语言原生支持注解。例如：

```java
class UserController {
    @OpenApi(
        path = "/users",
        method = HttpMethod.POST,
        // ...
    )
    public static void createUser(Context ctx) {
        // ...
    }
}

然而，对于像PHP这样的语言，注解通常依赖文档块注释，其本质上仍然是通过手动方式添加文档。例如：

/**
 * @OAGet(
 *     path="/2.0/users/{username}",
 *     operationId="getUserByName",
 *     @OAParameter(
 *         name="username",
 *         in="path",
 *         required=true,
 *         description="关于用户名字段的详细说明",
 *         @OASchema(type="string")
 *     ),
 *     @OAResponse(
 *         response="200",
 *         description="用户信息",
 *         @OAJsonContent(ref="#/components/schemas/user"),
 *         @OALink(link="userRepositories", ref="#/components/links/UserRepositories")
 *     )
 * )
 */
public function getUserByName($username, $newparam) {
    // ...
}

虽然这种方式看起来有些繁琐，但支持者认为将文档与代码结合可以更好地保持一致性。然而，即使使用注解，也需要采取额外措施来确保文档的完整性和准确性。

API设计优先的核心理念

与代码优先不同，API设计优先的核心理念是通过缩短反馈循环来提高开发效率。这种方法强调在开发之前，先定义API的结构和行为，从而确保API的设计能够满足用户需求。

然而，设计优先的方法也存在一些误区。例如，有些团队认为设计阶段是独立的，但实际上，设计和开发应该是一个持续演进的过程。无论是手动编写API代码，还是通过API描述文件生成代码，设计优先都需要与开发过程紧密结合。

此外，许多工具会维护API的独立版本，这可能导致团队之间的协作出现问题。因此，建立以API描述文件为单一可信源的工作流显得尤为重要。

设计优先与代码的共演进

在设计优先的工作流中，开发者可以使用工具（如API Studio）、领域特定语言（DSL）或手动编写API描述文件，从一个空的代码仓库开始。随后，开发者根据描述文件逐步编写代码。

这种方法虽然不能完全保证代码与描述文件的实时同步，但通过以描述文件为核心的开发方式，可以大大提高团队协作的效率，并减少因版本不一致而导致的问题。

通过设计优先与代码共演进的方式，团队可以更好地适应需求变化，同时确保API的设计和实现始终保持一致。

总结

API设计优先与代码优先各有优劣。代码优先方法适合快速迭代，但容易忽略文档的重要性；设计优先方法则强调在开发之前明确API需求，能够更好地支持团队协作和长期维护。

无论选择哪种方法，关键在于根据团队的实际需求和项目特点，选择最适合的开发模式。同时，借助工具和规范化的工作流，可以进一步提高开发效率，确保API的质量和一致性。

原文链接: https://apisyouwonthate.com/blog/api-design-first-vs-code-first/