用蚕茧表示法写简洁实用的接口文档

蚕茧表示法是一个接口描述的规范。我用它的一个典型的场景就是写内部接口文档。蚕茧法体现了两个思想：

1. 使用简洁的语法来描述对象、数组、字典等复杂结构。
2. 通过命名规范，让一个名字自发地体现出它的类型。如名词复数用于对象数组，以Id结尾默认是整型等等。

考虑一个移动互联网的产品，要做一个手机APP，前端通过某种RESTFul风格的接口规范来调用服务端接口，请求时通过urlencoded方式来传参数，返回内容采用JSON格式。假设现在需要一个查看订单的接口，返回订单详情，可以这样描述你的设计：

根据id获取订单：getOrder(id) -> {id, userId, dscr, total, %address, @lines}address: {country, city, street, name, phone}lines: [{itemId, qty, price}]

其中，返回对象使用了蚕茧法进行简要的描述，将复杂数据类型层层剥开直到基本类型，而基于命名约定，参数或属性的名称隐含了它的基本类型，无需再多解释。在内部团队，如果每个人（架构师，开发，测试人员）已经对产品中的基本术语如order-订单, item-用户购买的物品这些了解之后，上面的设计几乎不需要任何多余的描述文字，因为它已经清楚的展现了每个对象的数据类型和含义：

• 接口返回一个对象，包含id, userId等等属性。
• 其中address属性是一个对象，它又包含country, city等属性。
• lines属性是一个数组对象，数组的每一项是一个Line对象，它包含itemId, qty等属性。
• id是对象的主键，其它以id结尾的字段如itemId是指向其它对象的外键。它们都是整型类型。像total, qty, price这些是货币类型（Currency/Money/Decimal），分别表示总金额，数量和价格。其它属性未明确标示的都是字符串类型。

可以以这样简洁的描述让所有参与的人都能看的很明白，主要得益于大量的约定，比如利用蚕茧法描述对象，数组，字典等，再如良好的命名规范，不仅从名称中可以了解它的含义，也暗示出它的类型。

一个产品的内部接口会有很多，少则十几二十个，多则有上百个。怎样才能维护好它们？要不要有文档？应该怎样写文档？

笔者对内部文档的观点是：

• 接口需要有文档来记录。

  我见过很多小团队的产品根本没有文档，遇到接口不明确时都是直接找代码，看似省确很多事，实则为之后的维护埋下了雷。

• 文档也应纳入版本控制。

  原始文档应该使用文本类型。某个改动是谁做的，因为什么原因做的，只有应用了版本控制才能方便的做到问题追源。使用文本类型的文档（比如markdown, wiki等格式），一则方便比较版本间改动，二则可以生成html, word, pdf等多种美观格式。我见过有好多团队是使用word来写文档的，由于是二进制格式，不利于版本比较，也不专业。还有好多在文档在顶部还标有版本历史，以及是谁编辑的做了哪些修改这些内容，真的没必要（除非是特别重大的变化希望读者知晓），随便用svn, git等版本工具就可以做的更专业。

• 文档要在没有歧义的基础上足够简洁。

  很多文档描述很多，而真正有价值的内容并不会增加很多。比如参数或字段的描述，如果从名字就能很清楚的知晓它的含义，又何必再写一遍（或翻译一遍）呢，白白增加了很多开销，维护也麻烦了很多。文档不应浮于形式，而是力求只写最有价值的内容。做好这一点的关键是作者与读者要有足够的约定，比如蚕茧法就能很好的帮助简化类型定义的描述。

• 应有机制保证接口文档与代码的一致。

  一些团队在文档上应付差事浮于形式，在代码写完后，补一个word文档应付。在更新代码时，文档没有及时更新，导致文档都是错误没法看。好的做法都应先有设计再写代码，比如架构师或主程先设计好接口，然后再开始编程实现，在实现中发现问题再修正接口，更新设计文档，而不应是写完代码再补个设计。而在文档更新的具体做法上，也流行一种做法即文档以注释的方式内嵌于代码中，我称之为“格式化注释”，这样做到设计与代码在一起，更新也就更自然的同步了。之后再通过工具将注释抽出来美化给读者看。