在两个孵化器子公司高速成长的操作过程中，作为技师的你或许经常会碰到上面这种的情况。
有六天，你看到两个段标识符或两个演算法，真的这些标识符并不大经得住考究；只好你用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 绝对规范，又不得不放弃对某一些功能的直接支持，这些功能就只能通过插值调用或客户端预处理的方式来同时实现。
这种结构设计上的取舍，通常会列出所有可行的计划，从简单的结构设计到繁杂的结构设计；接着通过分析各种使用实例的频率和使用某种结构设计时的复杂度，从实际的系统需求入手，尽可能让常
用的功能得到最简单直接的支持；还要一定程度上“牺牲” 一些极少用到的功能，反复考虑系统使用场景，尽可能获得两个合理的折衷计划。
API 结构设计原则
在这个折衷的操作过程中，他们需要始终保证满足这些基本原则。
1. 保证API 100% RESTful。RESTful 的核心是：everything is a “resource”，所有的行为（Action ）和接口，都应该是相应Resource 上的增删改查（CRUD）操作。如果脱离这种结构设计模式，一定要再三考虑是不是必要？有没有其他计划可以避免破坏RESTful 风格。
2. 在请求和响应中，应该尽可能地保持参数的结构化。如果是两个哈希（hash），就传两个哈希（不要传hash.to_string）。API 的序列化和反序列化机制（Serialization /Deserialization ）会将其自动序列化成字符串。多语言之间的API，比如Ruby、Java、C# 之间的调用，通常都是在序列化和反序列化机制中完成不同语言间类型的转换。
3. 认证（Authentication ）和安全（Security ）的考虑。安全的考虑始终应该放在首位，保证对某一的用户永远只暴露相关的接口和权限。可以使用证书和白名单，也可以通Credentials Token Session / Cookie API Logging
过用户登陆的证书（感的信息。）生成的验证票据（），或者等方式来处理。此外，所有的层的日志，要保证不记录任何敏
4. API 本身应该是客户端无关的。也就是说，两个 API 对请求的处理尽可能避免对客户端是 移动端还是网页端的考虑。客户端相关的响应格式，不应该在 API 中同时实现。所有的客户端无关的计算和处理，要尽可能在服务器（Server ）端统一处理，以提高性能和一致性。
5. 尽可能让API 是幂等（Idempotent）的。关于幂等，可以参考我之前写的“谈谈幂等“一文。这里面有几个不同层次的含义。举例说明：同两个请求发一遍和发两遍是不是能够
保证结论相同？请求失败后重发和第一次发是不是能保证相同结论？当然，要不要做成幂等，具体的同时实现还要看具体的应用场景。
使用好API 框架
每一语言都已经提供了很好的API 框架，你需要在结构设计前先多了解这些框架。如果你是个小团队，资源没那么充分，选两个合适的框架入手，适当调整，比从零开始造轮子要好得多。等子公司长大了，由于各自业务逻辑的特殊需求，最终都会定制两套自己的API 同时实现计划。
评估两个API 框架，可以从以下几个方面考虑：
1. 对访问权限的统一控制
2. 自动测试的支持
3. 对请求和响应的格式，以及序列化和反序列化（Serialization 和Deserialization ）的支持
4. 对日志和日志过滤（Logging 和Logging Filtering ）的支持
5. 对自动文档生成的支持
6. 对构架以及性能的影响
结构设计中的平衡
API 结构设计中存在许多对立的因素，比如简洁还是繁复，兼容性和效率，为现在结构设计还是为未来打算等等。根据自己的工作实践，我给出以下观点供你参考：
1 自由总是相对的
就好像在两个群体里，如果没有规则，完全行为自由，就会出现各种难题。小群体还好，而对于两个大群体，有人就会被别人的”自由“误伤。
写软件也是一样。两个小的创业子公司里，API 怎么结构设计，标识符怎么写，几个人一协商，达成共识，并不需要那么多的条条框框，也照样行的通。
子公司越大，标识符协作的人越多，个人的自由就会在结构设计和同时实现中产生难题，并导致最终的冲突。所以，许多大子公司会制定一些API 的最佳实践，强制要求结构设计和同时实现中必须按照某种模式来做。
有些规则虽有规矩，但也不是说不这种不行，所以在许多时候，因为这种的规则，他们的API 结构设计中会有许多限制，这在表面上似乎给结构设计带来无谓的难度，但是仔细考量，从规范标识符和结构设计一致性的角度而言，还是有很大好处的。
2 为当前结构设计，还是为未来结构设计？
API 结构设计里很常见的两个情况是：一个目前并没有人使用的系统功能，它的存在只是因为有人提出：“这种情况他们以后应该要支持。” 前文中我曾讲过，由于API 上线后再改很困难，所以在结构设计初期就要尽可能地考虑未来的发展；但是这些“可能” 的应用场景因为需求的细节和使用频度都不明确，最容易造成系统的过度结构设计（Over-design ）。
我记得有两个API 结构设计的经典原则，概括一下就是：要考虑未来的场景，在结构设计时留有余地，但永远只同时实现当前产品真正要用的功能。
3 可维护性和效率（Maintainability v.s. Efciency）
结构设计和同时实现里经常会有一些封装和抽象的概念。某些特殊情况下，封装再分拆的操作过程可能会在一定程度上影响API 的响应速度，或者标识符质量的强化和性能的强化上有冲突。这个很难一概而论，具体的做法要看标识符是否在关键路径上，或者这段标识符是不是需要多人协作等等。最终的选择就要具体难题具体分析了。
4 是否采用AOP
AOP逻辑同某一领域难题的关系通过侧面来封装、维护，这种原本分散在在整个应用程序中的变动就可以很好地管理起来。
监控（Monitoring ）等等，所以API 成了AOP 两个很自然的应用领域。
；但也会自然而然地继承了AOP 固有难题，例如标识符的剖析（Profling）和调试（Debugging）困难增加，对开发人员的相关经验有更多要求，相互协作的要求也增强了，比如改变某两个功能可能会影响到其它的功能，等等。
是否选择使用AOP，和你的需求场景，人员技能和结构设计复杂度息息相关，需要技术决策者根据具体环境作出判断。
今天我从两个小故事情节入手，和你讨论了API 的结构设计和原则，内容分为四个部分：API 的亲笔签名、API 的结构设计原则、使用现有编程语言的API 框架、如何在API 结构设计中取得平衡。
API 结构设计是现代软件系统中不可或缺的两个环节，不同的系统需求和不同编程语言下，API 的结构设计都大不相同，但总有一些原则和注意事项是可以提取出来的，今天我和你讨论的就是这些通用的原则，希望对你的实际工作有帮助。
最后，给你留一道思考题，API 的亲笔签名（Signature）结构设计是语言无关的，那你在结构设计中会引入更多的语言还是更少的语言去同时实现不同的API 呢，优点和缺点各是什么？
复，他们一起进步。下期再见。
