先把 Joshua Bloch 大神的 API PDF 放在这里膜拜下：“How to Design a Good API and Why it Matters.pdf”
总述
在设计和实现通用订单搜索API的过程中，收获了一点关于API设计的得与失。总结下，希望能给后面的工作带来有益的帮助。
什么是好的API ？
简洁、清晰、易懂、易使用。 语义行为与选项分离。
- Easy to learn
- Easy to use, even without documentation
- Hard to misuse
- Easy to read and maintain code that uses it
- Sufficiently powerful to satisfy requirements
- Easy to extend
- Appropriate to audience
得：
从交易订单搜索能力化角度思考API，充分考虑了组合性，做到足够灵活，同时兼顾可读性。能够在较少改动和发布 trade-manage 的基础上，实现多样化的需求。
失：
在过于注重灵活性功能的情况下，有一些地方做的不够好，给使用方带来很多困扰。
本文主要讨论其得与失，希望能够给后来者带来有益的启发。
好的地方
能力化
强调从能力的角度而不是业务场景角度来思考API设计，考虑足够灵活性。 比如
- 定义交易订单搜索能力需要的参数，而不是依赖页面传过来的参数。通过定义的参数来组合搜索能力。
- 虽然搜索页面只需要传一个订单类型，但是后台允许传多个订单类型，为后续扩展性留下空间。
实现清晰
基于自身定义的订单搜索参数，后台实现也非常简洁，而不需要做各种参数的解析和适配。对于搜索能力的稳定性和减少BUG的发生，是非常有益的。
一体两面，总有正面和反面的地方。由于通用订单搜索API 特别强调基础层的能力化和稳定性，在基础层与业务层之间缺乏一道友好的适配层，给业务方使用也带来了不少曲折。
详细的文档
其实通用订单搜索API 的文档也做了不少工作。 接口入参 ，代码示例， 搜索入参的分类，包括代码里 java doc 其实也写得很清楚。 为什么业务方还来咨询呢？ 一个原因，确实 API 设计有失当之处（考虑了最主要的PC列表页面搜索场景），对于业务方的简单需求（比如按照下单人ID）显得过于复杂了； 另一个原因，我认为开发人员对于陌生事物还是缺乏必要的耐心。当然我其实也有这个毛病。 如果说文档没有，代码里 java doc API 也缺失，过来咨询是没问题的，但是文档 ，javadoc 注释写的很明白了，花2分钟稍微扫一下，能够学到更多东西，就不会为了一个小需求来咨询了。
但是文档确实也有写的不够的地方。
比如返回的错误信息，文档没有写明。于是联调的时候，业务方遇到“非法的调用源”，一脸懵逼。需要有一些错误提示文档 ； 比如业务方遇到其他的错误，也不知道是什么原因，只能找我们来查。
比如没有突出常用的需要的东西。往往业务方内部依赖订单搜索列表的时候，基于应用场景，可能更多依赖于 订单状态，订单类型，粉丝ID，下单人ID，维权状态, 这些可以单独抽离一个更 brief 的订单搜索接口，并辅以文档，也许就不会遭遇不知道用哪个参数的问题了。 换句话说， 原来过于依赖能力化的角度思考接口，缺失的一块是， 基于应用场景的角度来思考接口。
不好的地方
盲增参数
先说下背景。当时是因为老搜索接口不太灵活，且参数与前端页面耦合比较紧，因此决定设计一个新的通用订单搜索接口，以提供更加灵活的搜索能力。
第一个失，就是不加思索地把老搜索接口里的参数全部拷贝过来。 比如说 毫无卵用的 订单标记，被废弃还让业务方传错的 pageSize, pageNo 。
经验： 由于新接口上线和接入通常有一个过程，其实不必要立即支持所有可能的搜索请求，而是先支持最常用的部分，然后根据情况扩展能力。 API 参数通常是越严格越少更好，公开了就收不回来了。
- 设计新接口入参时，可以参考老接口入参，但一定要慎之又慎，只取必需的，严格把控每个参数的必要性。
- 参数一定要仅仅针对接口服务而言，不要为了图方便把所有入参都混杂到一个类里，导致API语义不清，给业务方使用带来困惑。
继承滥用
第二个失，过于追求复用代码和语义分离，继承层次比较深。
追求代码复用是好习惯，但不能过度。尤其 API 设计，应该以“清晰易使用”为重。 如下是个反例：
经验： 继承一般是为了实现不同的语义分离，比如基础通用参数与业务参数， 但强烈建议最多两层，继承层次绝不要超过两层。
public class PaginationParam extends BaseParam { }
public class GeneralOrderSearchParam extends PaginationParam {
protected String index = "trade_es_index";
/**
* 订单查询对象
*/
protected OrderSearchParam orderSearchParam;
// ...
}
public class OrderSearchParam extends BaseParam { }
使用体验不佳
第三个失，没有充分考虑业务方的使用体验。
层次感不强
所有的搜索参数都平铺到一个 OrderSearchParam 的字段里，没有层次感， 业务方往往只要根据一个字段搜索，却要在繁多的搜索字段里搜索。
构造入参不方便
缺乏方便的构造搜索入参的方法，业务方需要写很无聊的 set , set , set 来构造搜索入参，代码会比较难看。 可以考虑使用 Builder 模式来构造常用参数。这个方法也可以解决 层次感不强 的问题。
经验： 应该对搜索字段进行区分对待，重点突出， 可以将最常用的搜索字段聚合成一个子搜索对象，有关联语义的搜索字段聚合成一个子搜索对象。 让业务方能够快速找到所需要的。通过提供易懂的 API 示例，也可以帮助业务方更好地使用 API。
参数混杂
为了图方便，直接在原来的参数里加字段，而不是创造新的参数对象，导致原有的参数对象混杂不同的功能，给业务方使用带来困惑。
比如原来有个实时详情接口的入参 OrderQueryOptions ， 非实时详情接口，多了个 withDeliveryInfo 可选参数，虽然放在原来的参数对象会省不少事，可是会让接口语义不清。对应实时接口来说，它根本不需要这个参数；对于非实时接口，又混杂了实时接口的入参。 两边都不讨好。
经验： 严格对接口入参进行控制，与接口服务无关的参数不允许加入。实现细节相关的东西不加入API，不公开。
暴漏内部细节的扩展方式
为了具有更好的可扩展能力，减少发布，设计了一个入参 extendKeywords 。当要搜索的字段不在给定搜索入参时，可以直接指定 ES 里对应的字段及操作符来搜索。 虽然灵活了些，却将业务方与底层实现紧紧绑在一起。对于API设计与实现来说，都是不好的决策。
小结
API 是服务提供的接口抽象。 一旦公开，收回来会非常困难而且费力。因此，设计API 要精思细虑，严格把关每个入参字段、继承层次不要超过两次、充分考虑使用者体验、避免参数混杂、避免暴漏实现细节等问题。
API 好书推荐： 以前有个 IntellJ 平台的设计者写了一本 API 设计指南很不错的。忘记书名了。
原文地址：https://www.cnblogs.com/lovesqcc/p/9902305.html