API设计的七大误区

最新推荐文章于 2025-06-03 21:08:52 发布

转载最新推荐文章于 2025-06-03 21:08:52 发布 · 253 阅读

对于现在的绝大多数人来说，网站和移动应用已经跟空气和食物一样成为生活的必需品。然而在网站和移动系统不断演化的过程中，前后端分离是系统架构演化的一个重要分水岭。

随着系统逻辑和展示层分离的过程中，API 是一个实现这种分布式应用架构的重要机制，从早期单纯的 WebService 到 RESTful，API 的设计方法、技术和理念发生了巨大的变化。然而 API 的设计实在是陷阱重重，一不小心就会落入其中，从而连累整个系统。

如果单纯地考虑功能的话，大部分服务端开发工程师都可以设计和实现出一个说得过去的 API，但一旦有多个互相关联的 API，或者当系统压力达到一定级别时，就会有不少问题出现，甚至导致系统崩溃。

我们可以来看看常见的误区在什么地方。

1、API 就是 RESTful API

观点：RESTful 是现在很流行的一种 API 设计风格，有大量的文章在推荐这种方法，因此我们就需要按照这种风格的要求来设计API，并且要实现全套的设计！
真相：完全不需要！

事实上 RESTful 只是一种设计思想，并不存在具体必须遵守的规则。在不同的应用系统中，API 承担了不同的各种职责和功能，针对不同的应用场景可以使用相应的规则，适用就好。尽管有一些类似于Richardson成熟度模型这样的理论，但也都不是必须做到的。虽然最高级别的成熟度是很有用的，但也要求整个系统以特定的方式运作，对于绝大部分的系统来说，低一些级别的成熟度一样工作良好，并且同时不需要花费太大的代价。

如果实现了比较完整的 RESTful API，那么会有一些好用的工具和代码可以利用，但如果自己实现，也未必会有很大的代价。

2、API，不过就是一段 Java 代码么

观点：API？不过就是一些 Java 代码暴露一个 HTTP 地址么，找个会做 Java 的人上就行。
真相：大部分情况下都不是这样的。

这种说法，和“只要人会说话，就能进行感人的演讲”一样可笑。

（图样图森破）

软件工具的使用只是一种简单的技能，但在工具背后的思想是需要经过经验的积累以及各种周边知识的共同理解才能做到。

API 的设计与其说是一种技能，不如说是一种艺术，交流的艺术。除了代码编写以外，更多的是架构上的设计。API 是整个服务端系统暴露到客户端的接口，是所有业务逻辑提供给外部的界面，如果对于系统的整体要求和架构不了解，很难设计一个合用的 API 系统。

3、和交互绑定的 API 设计

观点：API 是给客户端用的，在现在 App 大行其道的时候，移动端的同事说，我们需要简化网络交互，所以每个页面只需要一个 API ——什么？我要调用8个 API？不行，太慢了，只要一个，把所有的数据都放在一起给我吧，谢谢！
真相：这样的做法会导致 API 最终完全不可用。

没错，从性能的角度上看，确实这样是比较好的，但是，有没有想过，如果移动端页面设计改变了怎么办？一旦增加或者减少这个页面所需要的数据，那么这个API 立刻就变得没用了，重新设计一个？算了吧，API 升级的代价太高了，于是越来越多的重复 API 就出现了。

前后端分离的理念在于把业务逻辑和展示分离，API 作为业务逻辑的体现，以业务逻辑作为设计原则，比靠拢易变的展示层要准确和靠谱得多。从这个角度上说，引入一个中间层来适应展示的变化会更加适合。

4、我的 API 是我的，你的 API 是你的，不互通的 API 设计

观点：系统 A 提供了一组 API，系统 B，恩，另外一个系统，所以我们需要另外一组 API，但是，不好意思，我不知道 A 是怎么做的，并且我也不关心。
真相：这是一种系统分裂的征兆，是系统业务逻辑混乱的表现。

如果把应用程序接口比做用户接口的话，这样的说法就很奇怪了。作为一个公司下的不同系统，长得完全不一样，互相之间没有任何关联性，这样用户在使用的时候会很别扭。如果把系统当成一个人，这样的设计就和这个人有两张脸一样奇怪。作为系统的架构师，要为全公司设定一个一致的API规范，程序员们对接入各个系统可以有明确的预期，并且非常有助于在系统和客户端之间共享代码，简化开发和维护的成本。

5、API = 数据库

观点：API 设计？简单，数据库的操作映射一下好了。创建一个对象，修改一个对象，删除一个对象，赞！API 设计的生活是如此简单。
真相：等一下，作为API的使用者，客户端应用为什么需要知道数据库？难道不应该是业务驱动的吗？

很多 API 确实就是这样设计的，但如果只是单纯地按照数据库的结构进行设计，那么只能说是一个数据库的访问层而已，是SQL 语句的 HTTP 化…… 但 API应当反映的是业务内在逻辑，包括业务对象、流程和业务数据，在基于数据库的基础上，通过服务器端的业务层处理后才是 API 应当的结果。

6、我的自留地 API，API 不开放标准

观点：我没打算开放 API 给别人用，所以也不需要遵守什么标准。
真相：标准意味着通用，有更多的简化。

话是不错，但标准的好处在于设定交流双方的一个基础，作为服务器对外的交流接口，API 始终是设计得给人用的，不仅仅是公司内部，也有可能是外部；不仅仅是现在，也有可能是未来的人在使用。和代码规范一样，符合良好规范的 API 能够极大地改善可读性、维护性，即使不开放给外部，内部交流也会获益良多。

7、我不说，你就不知道，API 的安全性

观点：这个 API 又没有公开，所以不需要加密的。
真相：在这个互联网上是没有秘密的，所以你不让人知道，不代表别人不会知道。

关于安全，这个是 API 设计中非常重要的一个需求，但很多 API 的设计师并不重视这个。最常见的借口就是这个，我不告诉别人，谁也不知道。但事实上，API 作为交流的工具，即使服务端不容易被窥视，但大量的客户端几乎是不设防的。破解一个客户端系统并不是一个多么困难的事情，因此了解这个 API 的调用也不是太复杂的事情。

此外，在网络上的传输也是不安全的，中间人截获信息的案例导致无数的系统被攻破。按照业界的推荐方法来设计 API 的安全传输功能，尽管开发的代价会略大一些，但远比自己自以为完美的设计安全得多。