说起API，做开发的人大概都知道也用过，我也是如此。不过除去使用，我还亲眼目睹过API制定，参与搭建过开放API平台，也与合作方商量确定过API方案；算是各个方面都有了解和经历，感受过让人啧啧称奇的赞赏，也经历过举步维艰的尴尬。目睹还有很多同行在API的泥泞里挣扎，我把自己的经验写在这里与大家分享。
大家都知道，API是Application Program Interface，也就是应用程序接口，看起来非常容易理解，实际却并非如此。据我观察，不少API方案之所以陷入了泥潭，就是程序员对API理解错误，把它看成了“对外开放的函数”：某个动作可能之前需要用户鼠标点击触发，现在开个口子给程序用消息触发，这就是API了；推广开来，现在流行的API化、开放平台的潮流，无非是多开一些这样的口子而已。
据我观察，相当多的程序员是这样理解API的。这种理解不能叫错，却往往造成严重的后果。因为它的关注点更侧重“应用程序（Application Program）”，而不是“接口（Interface）”，而两者是有很大差别的：应用程序是一种具体的实现，说到应用程序往往想到的是代码，它是具体、容易理解的；而接口是对抽象行为的封装，说到接口，往往想到的是某个动作，是虚拟、不那么好理解的。此外，接口还蕴含了“解耦合”的意义：应用程序往往是知根知底的“内部人交易”，出了问题也很好变通解决，接口却要暴露给未知的外部世界，只能依靠相对固定的规范加以约束。更重要的是，接口往往会影响甚至塑造外部调用方对系统的认知，在调用方看来，系统对外提供了几个接口，可能就只有几个环节（或几个方面）。如果对接口的理解不到位，开发出来的API往往是残缺的，根据接口（Interface）的首字母I在英语中的意思，我把这类API称为“迷失自我的API”。
举个真实的例子，我们常见的表单填写功能，为了保证用户体验，往往会把整个填写分为几步依次进行。相应的，后台有方法对应每一步的处理。为了提供API，程序员直接把后台每一步的处理包装暴露出来，而没有想到应当“填写表单”是逻辑意义完整独立的操作，之前拆分开来只是为了保证直接交互的体验，结果客户端应用程序在调用时，也不得不把整张表单拆开了分次调用，这样的API既没有效率又没有准确性。
再举个例子，在某个界面上客户可以选择确定的服务，原有系统里表示服务的是枚举类型，因为都是项目内部调用，所以没有问题。提供API时，程序员直接把这些参数和类型通过WSDL暴露出去，初期用起来一切正常，不久就问题丛生：因为服务的种类经常随业务变化，枚举类型本身也会变化，内部更新并不是大问题，客户调用起来则痛苦不堪，哪怕服务的值没有变化，也必须重新编译。
以上两例，都可归类为迷失自我的API，因为都是对接口的理解不到位：第一例是没有设定合适的粒度，第二例是没有设定信息隔离的合理边界。在实际开发中，这样的例子还有很多，结果都是浪费了大量的人力物力（让API调用方跳起脚来大骂的情况也屡见不鲜）。根据我的思考，要避免这类情况，可以从以下几方面采取措施。
第一，要重视API，抽调最好的开发人员负责API。在许多团队里，开发API被视作脏活累活，交给开发能力一般甚至比较弱的人员去开发，这一点是要严格杜绝的。API的设计和开发是一项要求很高的工作，如前文所说，负责人员要理解每个API对应的逻辑意义以便合理划分粒度，还需要根据实际情况进行合理的隔离。更重要的，相对普通的函数调用，API的调试和报错都需要精心设计。我见过很多程序员随便应付错误处理甚至干脆一股脑扔给虚拟机，这种水平去设计API只会让调用方欲哭无泪，最终还可能搬起石头砸自己的脚。如果抽调了最好的开发人员负责API，哪怕内部暂时逊色一点，稍后也可以改过来，这个道理反过来则不成立——用优雅接口包装起来的龌龊实现，通常强过龌龊接口包装起来的优雅实现。
第二，自己开发的API要自己调用。软件开发行业有句话叫“吃自己的狗粮”，意思是自己做的程序自己用，才能真正知道自己做的如何，API也是如此。难用的API通常有个共同特点，就是开发API的人自己是不用的，对他们来说纯粹是摆设，所以他们无法设身处地评判API的好坏，发现有问题也没有动力去改善，即便有压力去改善，也往往难以找到合适的切入点，向合适的方向推进。实际上，目前很多项目已经实现了内部API化，自己调用自己的API已经是必须的选择，这时候开放API也变得易如反掌。我相信这是一种好的架构方式，值得推广开来。
第三，API是有章可循的，借鉴现成的成功经验会少走很多弯路。API的设计和开发虽然是一项要求很高的工作，但经验并不是要求的全部；目前已经有了很多论述API的文档资料，涵盖了从实现到架构的各个方面；业界也有许多公认的规范优秀的API，很多领域都可以找到API的榜样（FourSquare、Twitter、Facebook，都是很好的样板）。如果能多加学习，多加思考，甚至稍加思索直接照搬，都会比自己盲目设计开发要好很多（国内的一些直接照搬国外的API至少像个样子，许多“自主设计”的反而非常糟糕）。
说句玩笑话，API没有了I，就“迷失了自我”。正是众多迷失自我的所谓“API”，给广大程序员造成了无穷无尽的困扰。我衷心希望这种境况能早日得到解决。
From Life Sailor, post 迷失自我的API
之前我写了一篇《坚持了两年之后，小朋友突然不想去打冰球了…》，本来是无心之作，没想到收到了很多留言，我自己也获益不少。 本来，我以为解决了小朋友的问题，此事就这样过去了。没想到的是，暑假过后，冰球训练重开，他又老调重弹：“我不去了，我不想打冰球了……”。 这可叫我如何是好？听到他嘟嘟囔囔说这一切的时候，我心里百感交集。 成年人的生活里总是有忙不完的事情，对应的，也希望一切井井有条、按部就班。因此，这样“意外”的变数，总是第一时间让人心生无奈和烦恼：天哪，怎么会这样呢？为什么会这样呢？ 不过，基于之前的经验，借鉴大家的留言，这次我显然更有心理准备一些，起码不会慌乱。 之前我写过，如果父母多阅读一些高质量的育儿专著，有助于把自己的期望水平“降”到合适的程度，就不会那么焦虑甚至抓狂。 (more…)
认识Michael很偶然，但我也很幸运，因为我见证了一个“打冰球的好孩子”的成长。 最早认识Michael是在冰球队的夏季体能训练上。那时候这群孩子还只有六岁左右，每次训练都是家长送来，在旁边观看陪伴，再接回家。但是，我很快发现有个孩子不一样，家长送他来就回家，他靠自己换好全身装备，训练完自己洗澡更衣，再由家长接回去。看起来，他好像完全没有其他孩子那种“害怕独处”的感觉。 于是我问他：“小朋友，你这么勇敢，你叫什么名字呀？” 他说：Michael。 我尝试复述他的名字，好几遍都不成功，因为我总听成“米歇”，最后他耐着性子慢慢说，我仔细听才发现最后还有个音节，嘴要更扁一点，舌头往上垫，才可以念出来，类似“米歇-厄尔”。其实这个名字写出来大家都认识，英文里读作“迈克尔”，无奈德语的发音规则很严格，字母i不会像英文那样有两种读音，结尾的el又一定要发音，所以就成了“米歇-埃尔”。 (more…)
偶然刷到一篇文章，说的是“贵族家长”群体给小朋友安排的活动：冰球、马术…… 我有点诧异，原来“冰球”也被贴上了“身份”的标签。想想自家小朋友的情况：赶上打折花了400多欧元买的全套护具，80元买的二手冰球包，每个月60欧元的俱乐部费用……想了想，似乎很难和“贵族”联系起来。 只不过，他已经坚持打冰球到了第四年，我们的生活确实有不小的变化。写下来，既是对自己有个交代，也可以作为“贵族运动”的现身说法。因为在我看来，如果非要说它是“贵族”运动，也只能“贵”在高（时间）投入、高产出而已。细细想来，我们的生活，已经被冰球深深的影响了。 (more…)
一 很多人关心，我们父子给M写了道歉信之后，对方是否有回应。 答案是：到目前为止，还没有任何回应。不过比较特殊的是，写完信之后德国小学就开始放秋假，学生不用去学校，既然见不到，也就不可能收到任何回应。 老实说，我觉得对方父母是有点反应过度的。这些年我的一条深刻经验是，如果出现分歧、矛盾，越早、在越低的层面直接面对，就越容易解决。许多小的矛盾之所以越闹越大甚至无法收场，往往都是经过了很多演绎、传话，而没有在一开始就开诚布公地面对。 试想，如果自己的孩子收到写着“我要杀了你”的信件，哪怕一开始很惊慌甚至愤怒，但仔细想一想，毕竟还有很多信息是未知的——比如对方是谁，平时言行如何，为何要写这样的信…… 更好的办法或许是先去直接寻求这些问题的答案，而不是直接把信交给家长委员会，走“公事公办”的路子。 我当然承认，“公事公办”无可厚非，对方家长也有这样的权利——所谓权利，就是“有资格做对方不喜欢的事情，人家还拿你没办法”。既然有这样的权利，就需要尊重。 所以，“严于律己，宽于待人”的确是与人相处的重要法则：我不会选择这么做，但我能理解和尊重你这么做的权利。 也有人问，那将来你遇到M的父母，会不会紧张？ 答案是：不会。 (more…)
一 收到S老师邮件的时候，我刚刚胆战心惊地做完第一次德语技术分享，还在享受着同事们的鼓励。猛然间就收到一封邮件：“您的孩子在学校参与了一起性质严重的事件，您必须来学校面谈，请从以下时间段中选择……” 什么？“性质严重的事件”？我揉了揉眼睛，确认自己没有看错。再把这段文字贴到谷歌翻译里，确认自己没有理解错。 我没有看错，也没有理解错，就是“性质严重的事件”。好吧，既然“性质严重”，那谈话肯定是越早越好，最早的日期是第三天。我紧赶慢赶，回信确认了最早可能的谈话时间，虽然德国人通常都不期待能这么快收到回复。 去接他回来的路上，我发现他一切正常，完全看不出任何异样。于是，我也没有表现出任何异样，只是依照惯例，问他当天发生了什么，在学校开心不开心。 得到肯定的答复之后，我心生疑惑，看起来和“性质严重”完全不搭边。那会是什么事情呢？ 我又问他，有没有和同学吵架、打架，是不是被人欺负了不敢说。但是，答案全都是“没有”。 我满心怀疑，又按捺不住，直接问：“既然一切都挺好，为什么S老师给我发信，说让我来学校跟她谈话呢？”我担心“性质严重”会吓到他，故意隐去了这个词。 他的满面春风在那瞬间凝固了，喃喃低语道：“好吧，原来是那件事，我还以为她不会跟你说。” (more…)
在2024年之前，我从来没想过自己有一天还可以加入乐团，甚至参加音乐会演奏。我只是个普通中年人，在之前文章里说过，上世纪八十年代随大流弹了十年手风琴，考过六级（当时最高八级）之后就彻底放弃了。直到二十多年后，在上海工作时才重新开始弹琴，当时有幸跟夏老师学了两年，打开了感官，懂得了音乐的世界远远比考级要广阔和美妙。再往后，就是自己看Youtube学习了一些乐理知识。因为德国几乎每个城市都有很多音乐学校，2023年末，我给本市的音乐学校写信，询问是否可以参加手风琴课程。通过回信我才知道，原来不只是“每个城市都有很多音乐学校”，而且“每个城市都有很多乐团”，哪怕是手风琴乐团。就这样，阴差阳错的，2024年初，经过简单的试奏，我加入了本市的手风琴乐团。虽然我是乐团新人，仍然有很多要学习的，但是一年下来，确实有不少感受。如果读者朋友也对音乐感兴趣，或者想让孩子学习音乐，也许我的感受可以提供一些参考。 (more…)
View Comments
从RPC到REST的风格变化，也是一种思考方式的变化，强迫自己以“对外开放资源”的方式思考API，会有很多好处。
反之，不自觉的回到Function Call的思路，难免会出问题。
老庄你怎么总是能几句话点到问题的实质？这样看来我废话一堆呀……