18 | 每个工程师都应该了解的：API 的设计和实现
朱赟
该思维导图由 AI 生成，仅供参考
在一个初创公司成长的过程中，作为工程师的你也许常常会遇到下面这样的情况。
有一天，你看到一个段代码或一个算法，觉得这些代码不大经得起推敲；于是你用 git blame 命令去寻找代码的主人；结果发现，原来作者是如今早就不写代码的 CTO 或 VP。
之后，在一个偶然的机会里，你和他讲起这件事，他会自豪地告诉你：“哦，那时候我们必须在一天之内做出这个产品特性。当时也就我一个程序员吧，一天的时间，这是当时能做出最好的方案了。” 说完，他便陷入了对美好时光的怀念里。
你也可能听说过这样的故事。
有一天你的 CTO 突发奇想，行云流水地提交了一段代码；大家一看很激动啊，很多人跑去观摩大神的代码，结果觉得问题多多，于是在 PR（ Pull Request ）上提了一堆评论。
CTO 一看有点傻眼了：“几十条评论……现在代码要这么写啊，好麻烦。”于是他就和一位工程师说：“你把评论里的问题解决下，合并（Merge）到主分支吧”， 然后就开开心心地该干嘛干嘛去了。
这两个小故事是想说明一个道理：一个公司早期的代码会因为各种历史原因不是那么完美，但是，在特定的时间点，这就是当时最优的方案。
随着公司的发展，成品功能不断叠加，代码架构不断优化，系统会经历一些从简到繁，然后再由繁到简的迭代过程，代码的改动也会相当巨大，也许有一天，你会几乎不认识自己当初的作品了。
API 的设计和实现更是如此。在我们的工作中，很少能见到 API 的设计和实现从最开始就完美无瑕疵。一套成熟的 API，很多时候都是需要通过不断演化迭代出来的。今天我就和你聊聊 API 的设计和实现。
首先第一点，我们先从 API 的签名（Signature）说起。
API 的签名（Signature）
API 的签名，或者叫协议，就是指 API 请求（Request） 和响应（ Response ）支持哪些格式和什么样的参数。
首先，做过 API 的人都知道，一个上线使用的 API 再想改它的签名，会因为兼容性的问题痛苦不堪。因此，API 签名的设计初期，一定要经过反复推敲，尽量避免上线后的改动。
除了一些基本的 RESTful 原则外，签名的定义很多时候是对业务逻辑的抽象过程。一个系统的业务逻辑可能错综复杂，因此 API 设计的时候，就应该做到用最简洁直观的格式去支持所有的需求。
这往往是 API 设计中相对立的两面，我们需要找到平衡。有时候为了支持某一个功能，似乎不得不增加一个很违反设计的接口；而有时候我们为了保证 API 绝对规范，又不得不放弃对某一些功能的直接支持，这些功能就只能通过迭代调用或客户端预处理的方式来实现。
这种设计上的取舍，通常会列出所有可行的方案，从简单的设计到繁杂的设计；然后通过分析各种使用实例的频率和使用某种设计时的复杂度，从实际的系统需求入手，尽可能让常用的功能得到最简单直接的支持；还要一定程度上 “牺牲” 一些极少用到的功能，反复考虑系统使用场景，尽可能获得一个合理的折衷方案。
公开
同步至部落
取消
完成
0/2000
荧光笔
直线
曲线笔记
复制
AI
- 深入了解
- 翻译
- 解释
- 总结
在初创公司成长过程中，工程师常常会面临代码质量不佳的情况。本文通过两个故事，强调了随着公司发展，代码和API设计都需要不断迭代优化。首先讨论了API签名的设计，强调了在设计初期就要经过反复推敲，尽量避免上线后的改动。同时，提出了API设计原则，包括保证API 100% RESTful、保持参数的结构化、认证和安全的考虑、API的客户端无关性以及幂等性的重要性。此外，文章还强调了使用好API框架的重要性，并提出了评估API框架的几个方面。总的来说，本文通过讲述故事和提出设计原则，强调了API设计和实现的重要性，为工程师提供了有益的指导和思路。文章还探讨了API设计中的平衡，包括自由与规则的关系、为当前设计还是为未来设计的考量、可维护性和效率的权衡，以及是否采用AOP的讨论。这些内容提供了对API设计的深入思考和技术决策的指导，对于工程师在实际工作中具有重要的参考价值。
仅可试看部分内容，如需阅读全部内容，请付费购买文章所属专栏
《朱赟的技术管理课》，新⼈⾸单¥59
《朱赟的技术管理课》，新⼈⾸单¥59
立即购买
© 版权归极客邦科技所有，未经许可不得传播售卖。 页面已增加防盗追踪，如有侵权极客邦将依法追究其法律责任。
登录 后留言
全部留言(12)
- 最新
- 精选
未设置置顶感觉安姐讲这个「每个工程师都应该了解的」系列，比其他的文章长了三倍都不止，安姐一定是特别喜欢技术类的内容，谈起来洋洋洒洒。技术小白看起来有点难，不过有认真的做笔记。 我还在学习阶段 没有上手做内容 不过感觉api的设计和实现这篇讲了很多细节的问题 十分有帮助 谢谢安姐2017-12-2411
蓝翔Sean置顶安姐 对于API的RESTful有一些疑问 感觉并不是所有的API都能实现成RESTful的 有很多内容是没办法找到对应资源的 比如说login logout 用户其他的一些动作 对这些API的设计有什么建议吗池建强回复: 大部分都可以，你说的 login 和 logout 都是 API 啊，看看 time.geekbang.org 的账户系统就知道了
2017-12-223
王岩关于login in/login out，在我现在系统里，就是对于特定授权的创建/删除哈 /auth post和delete2018-02-053
Y024
API框架可否推荐简评下呢？2017-12-283- gggjtg如果有英文版就好了2018-03-292
刘剑我们使用Spring Boot构建RESTful风格，我建议用更少的语言实现API以降低系统复杂度，也降低维护成本。2017-12-282
王宁建议使用更少的语言创建这样可以通过通用的Aop,日志，限流等功能的实现，对外提供一套统一的api交互方式。 如果实现多语言的实现，可以通过rpc的方式进行封装。 当然如果系统足够复杂也可以通过service mesh的sidecar的方式进行管理。2018-05-121
赖晓强还不太能看懂，先做笔记。2018-02-051- 何慧成偏向用更少的语言实现，语言比较集中，减少维护成本，减少对各种技术人员的需求。2020-08-23
mikejiang不同的api引入的语言似乎越少越好，可维护性更好，设计风格更容易一致。不过在追求性能与效率的同时，怎么折中就视情况而定了2019-11-12
收起评论
