月度归档：2023年09月

聊聊 APILetter 的新计划

聊聊 APILetter 的新计划

发表评论

APILetter 从创刊号，到 S1E6，经历了一年的时间。

虽然在定更新节奏时，我就考虑到自己拖更的可能性，但确实没想到我拖更这么严重，在 2022 年，一口气更新了 3 篇，然后就是长达半年的拖更。不过，总算是把第六篇写完，算是给 Season 1 做个了结。

过去

APILetter 的出现，是源自我在研究 RESTFul 架构时发现的问题：国内有太多解释什么是 RESTFul 规范的文章，但你点进去看，篇篇都是复制粘贴。

而 API 是开发者生态中非常重要的一环，它不应该被草率的对待，开发者们值得用上更好的 API。既然没有人写关于 API 的严肃内容，那就从我开始吧。刚好我在研究相关的内容，那就写一些 API 到底应该是什么样的。

也正是抱着这个想法，我开始了一篇篇的创作，从 为什么是 RESTful API，到如何设计一个符合 RESTFul 风格规范的批量操作 OpenAPI；有务实的内容，也有务虚的内容。但不变的是希望让大家明白如何设计一个更好的面向开发者的 API。

但，Season 1 的内容也是杂乱无章的，聊过 RESTFul、聊过 API 文档、聊过 API 指标、聊过 API 报错，这样杂乱且没有主线的内容，作为博客来说，还算可以接受，但作为 Newsletter，可能就显得过于随意。因此，在 Season 2 开始，内容也会开始面向主题，我也会更早的设计不同的 Season 要讨论的话题，以便于让你可以有更好的阅读体验。

未来

在写第一篇邮件通讯时，我就注册了域名 APILetter.com，因为我知道这件事我应该会做很久，所以搞一个独立的站点是必然的事情，也是符合我习惯的事情 —— 每搞一个事情，就要给它一个独立的品牌。

而在刚开始写第一封邮件时，我是没有勇气使用独立的站点的，我总担心自己写完第一封就写不下去了。那搞一个独立的站点不过是浪费时间。所以我选择从竹白开始我的写作之旅。一年过去了，获得了还算不错的效果（至少比我想象中的要好一些）。

迁移到 Ghost 之前的数据

不论过程是否艰辛，总归我是完成了自己对自己的承诺，至少写完了一个 Season 的内容。

而 APILetter 完成了第一阶段的产出后，下一个阶段，我希望用更加品牌化的方式来运行这个项目，便启用了 APILetter.com 的域名），并搭建了 Ghost 来托管这个项目。

换到 Ghost，除了域名独立、程序独立、数据独立，相应的，自然也有一些好处 —— 比如可以 RSS 订阅了。如果你希望通过 RSS 的方式来订阅 APIletter， 也可以直接访问 https://www.apiletter.com/rss/ 来订阅。

Season 2：指标

在 Season 1 中，我花费了不少的篇幅来讲 OpenAPI 的设计问题。在 Season 2 ，我想专注于 OpenAPI、开发者体验中的指标问题，从企业和个人制定目标开始，到具体到某一个具体的 OpenAPI 指标评定。

目前预计会包含的内容：API 自身的指标定义、API 相关业务的指标定义、开发者体验中的一些指标定义。

除了这些指标，你还关注哪些指标？欢迎回复邮件告诉我。

总结

总之，APILetter 在新的一季里，我会尽量以更好的内容组织方式、更高的频率（但暂时承诺还是每月一封哈），来给大家分享我自己关于 API、关于开发者体验，以及一切与开发者有关的内容，希望可以帮到你。

如果你身边有对于开发者关系感兴趣或从事相关内容的朋友，欢迎你将 APILetter 介绍给他，帮助我获得更多的读者，以及，持续的写下去🥰。

为什么 OpenAPI 的设计如此重要？

为什么 OpenAPI 的设计如此重要？

发表评论

在 APILetter 的 S1E6，我想和你聊聊 OpenAPI 设计的重要性。

在整个 S1 的文章中，我用了接近 4 篇的篇幅来介绍 OpenAPI 的设计，从一开始介绍为什么要使用 RESTFul ，到 API 的错误码设计理念，辅以批量接口设计的实例，再加上最后这篇重要性的强调，三分之二的比重，意在让你深刻认识到，OpenAPI 的设计至关重要。

为什么 OpenAPI 的设计如此重要？

在企业内部工作时，常常需要找到平衡质量和速度之间的折衷方案。当项目时间非常紧迫时，往往会牺牲一些质量。但如果项目有足够的时间，就有更高的概率能够设计出一个质量更好、开发者体验更佳的 OpenAPI。

然而，OpenAPI 是一项非常重要的任务，不能马马虎虎。一个坏的设计会让团队持续在 OpenAPI 开发上投入更多的精力。

沟通难度高带来的维护成本增高问题

和企业团队内部使用的 API 不同，OpenAPI 的用户是内部团队，用户的差异决定了沟通的难度的。

在内部API中，若需要对某个API进行不兼容变更，我们可以通过比较简单的沟通完成变更的通知，并通过企业内部的优先级对齐方式来明确变更的时间和行为。

但对于OpenAPI的用户来说，不兼容的变更意味着需要通知所有的外部开发者，并确保他们完成相应的更新。然而，这个时间节点和周期并不容易控制，跨企业的优先级对齐、时间节点对齐、以及出现问题时的技术支持，都可能会导致OpenAPI变更周期变得非常长，让维护人员感到疲惫不堪。

以平稳迁移为例，通常需要1-2年的时间才能下线OpenAPI。如果没有平缓过渡，那基本上就无法下线API了。

无法下线的 OpenAPI 最终将会指向不断增加的维护成本。毕竟，即使我们可以不在旧版的 OpenAPI 中去提供新的 Feature ，但依然要针对旧版本的 OpenAPI 提供安全更新，这会导致团队的研发成本越来越高。

风格/设计不统一带来的开发者评价问题

OpenAPI并不一定非要选择 RESTFul 风格，但一定要统一设计风格。

好的设计风格一方面是开发者对于美和好的追求，另一方面也会是开发者对于你的能力和团队水平的评估纬度。开发者可以通过对于接口风格、文档质量等多个角度的评估来评价你的产品的质量和结果。

虽然开发者并非企业的绝对决策者，但对于那些高度依赖开放性和集成性的业务而言，开发者的评价尤为重要。出色的开发者评价，将会使企业在进行集成相关的决策时，更加放心地进行选择。

当然，风格/设计不统一带来的也不仅仅是开发者评价问题，还涉及到更多的维护成本问题：

  • 因为风格不统一，导致开发者对于不同的接口没有一个明确的范式，需要理解成本带来的学习成本高的问题。
  • 因为风格不统一，导致开发者需要针对不同的接口做不同的适配层，重复建设。
  • …

美与好不是一个 OpenAPI 在发布时必须要追求的，但又是你大规模获客时一个重要的对比项目。所以，在 OpenAPI 的设计早期，定义接口设计规范是一个值得投入时间和精力去思考的事情。

如果我的设计已经不好了，又该如何处理？

绝大多数人没有机会从头设计一个全新的 OpenAPI 系统，大多是需要一边跑一边换轮子的。

在这种情况下，可以考虑为你的 OpenAPI 设计一个明确的下线策略，以及，做好你需要花费一年的时间来做好这件事的准备。先定下统一的 OpenAPI 规范，并通过大版本迭代的方式，将旧版中的设计不好的 OpenAPI 重新梳理、设计、整合，并开放出新版的 OpenAPI 出去。

再将存量中设计不好的 OpenAPI 标记为 deprecated，引导增量开发者升级使用新版的 API，卡住存量的 API 的新增使用用户。

随后，只需要不断在新版的 API 中提供新的 Feature，使用自然的产品策略方式诱导开发者来升级，从而实现存量 API 的自然退役即可。

总结

和企业内部使用的 API 不同，OpenAPI 的开放属性决定了 OpenAPI 是很难退役的，因此，从一开始就朝着最好的方式来演进，可能才是最正确的做法。快速迭代，快速试错的路子，并不适合 OpenAPI 的产品形态。

《不租房的606天》书摘

《不租房的606天》书摘

发表评论
  • 或许，真正的交流障碍不是语言，而是内心的自我设防。不能在被别人否定之前，先否定了自己
  • 工作最认真的人不是因为他们自律，而是因为他们在解决切实的问题，并且解决问题的过程让他们每天精神振奋
  • 德鲁给毕业生的人生信条是“网球”“圆圈”和“三万天”。“网球”代表我们所热衷的事情，把网球扔出去，小狗会追着网球疯狂奔跑，意思是人应该追求自己热爱的事业并为之奋斗。“圆圈”的意思是，每个人都会被身边接触最密切的五个人所影响，这五个人就是你的圈子，因此要多和给你启发的人相处。而人生只有“三万天”，我们永远没有准备好的那一天，所以想到什么就去做。
  • 我的手账里有一句留言：“最好的作品是你度过的时光。
  • 经历过富足的生活，他说：“丰富的精神世界比物质更重要。”
  • 对于我下一步是留在硅谷还是从事自由职业的困惑，他说：“辰雨，想让梦想照进现实，第一步是想清楚自己要什么；第二步是精练地表述需求，并努力争取。你有太多的恐惧，成功过一次，你就会越来越有自信。”
  • 多诺万对我说：“辰雨，勇气就是在恐惧中有所为。”
  • 离开后，我心中一直默念着他送我的三句话： 1.放下心中对拒绝的恐惧。 （Let go the fear of rejection.） 2.只要你成功一次，后面就会越来越有自信。 （Confidence is built on top of success.） 3.知道你想要什么，并主动争取。 （Know what you want and ask for it.） 火人节结束后，我收到一封邮件，落款是“你的新朋友多诺万”。
  • 早餐已经不再是一顿饭，而是打开话匣子、化解陌生感的方法，同时自带“刚刚好”的界限感。早餐不像晚餐过于隆重，时长恰到好处，房客既容易参与其中，又不会越界。
  • 25年飞龄的机长，三生三世的人生智慧
  • 我问他：“你会用一个什么词来定义自己？”他不假思索地回答：“梦想家。”
  • 对于大部分人来说，年纪越大，会越渴求陪伴。而丰富的人生经历，练就了卡尔一颗坚定的内心，屏蔽了外界的杂音，在精神世界里，从容安宁。
  • 拉斯维加斯不止有赌场，金发女郎也不都是花瓶
  • 如果不是因为工作，我很难找到一个再来这里的理由，但我想起导师的一句话：“若你感到不舒服，意味着你会学到更多。若你感到害怕，那正是机会降临的时刻。”
  • 离开拉斯维加斯时，我不再认为它是一座只充斥着堕落和罪恶的迷醉之城。撕掉游客给它的标签，这座城市向我展露出它质朴和生活化的一面。或许多一点时间了解，每个人都和这座城市一样存在着有趣的另一面，只有抛开成见，才有机会发现他们的特别之处。
  • underline
  • 工作只是定义人的一个维度，可能限制了我们看待陌生人的角度。克里斯塔也许平凡，却有超出常人的精神追求——人到中年，她挑战一成不变的工作，选择帮助犯过错的人改过自新，她的善良改变了我对罪恶之城的理解。她有经济压力大的烦恼，但也有对生活品质的追求，还十分热情好客。虽然我和克里斯塔的外表和职业都完全不同，但当我们敞开心扉沟通时，就会发现彼此的默契远大于差异。其实，每个人心里都藏着一座花园，等待你去探索。
  • 82岁的“文艺复兴”女画家，每天都是工作日
  • 身为美术系教授的托比，做事十分严谨，她还出过一本书——《画家生存指南》（The Artists’ Survival Manual：A Complete Guide to Marketing Your Work）。如果我忘记在画作上标注日期和名字，她会提醒我：“你又忘记写版权信息了。”几分钟后，她发来一封邮件，附件名为“画家如何管理知识产权”，内容来自书中的一个章节。
  • 跟我去趟火人节吧
  • 到达黑石城的时候，参与者会拿到一本《火人节手册》，上面写着：作为市民，在这座城里，你可以什么都没有，但是你需要遵守10条原则。 绝对包容（Radical Inclusion） 无条件给予（Gifting） 去商品化（Decommodification） 自力更生（Radical Self-reliance） 自我表达（Radical Self-expression） 有社区精神（Communal Effort） 承担公民责任（Civic Responsibility） 不留痕迹（Leaving No Trace） 积极参与（Participation） 活在当下（Immediacy） 正如伊莎在电话里叮嘱我的，物质准备之外，更重要的是调整好心态，要时刻记住“分享、感恩与自我表达”
  • 火人节令我豁然开朗，让很多不可能变为可能，正如我在一个艺术装置上看到的一句话：“向内看，可以找到一切答案。”（Everything you need is within you.）
  • 我想起《小王子》中狐狸说过的话：“仪式是经常被遗忘的事情，它使某个日子区别于其他日子，使某一时刻不同于其他时刻。”
  • 生活原本平淡无奇，是人赋予了它特定的意义。犹太人的晚宴让我想起火人节上绘有一双眼睛的艺术装置，上面写着：“我们也许不能改变这个世界，却可以改变看这个世界的眼睛。”
  • 或许这就是村上春树说的，“相逢的人会再相逢”。
  • 生活中我们会遇到很多人，一面之缘便成了微信联系人。或许在未来的某一天，当你遇到困难，他们也会伸手拉你一把，却不求回报，就像下雨天递上的一把伞，酷暑天送来的一瓶水。朋友圈的每一次举手之劳，于我都是雪中送炭，温暖并激励着我。
  • 利用工作间隙说走就走，不是为了潇洒，而是来自对生活的热忱和一点“贪心”。
  • 相比于结果导向的“事业”，365天住民宿是我了解世界的方式——每间民宿的个性和小瑕疵都在讲述着每扇门背后的故事。在墨西哥画家家里“吃的苦”看似是“代价”，但更是一分收获。比起在美术馆里看射灯下的画，我更喜欢被画家的作品包围，直观地感受画家的生活状态。
  • 很多次，我盯着心仪的民宿看了很久，鼠标停留在预订页面，却迟迟按不下“预订”按钮，只能默默地把房源存到心愿单。我常想：“如果金钱不是这个项目的阻力就好了。”每到此时，我会意识到，只有更加努力地工作，才能坚持过“既可朝九晚五，又能浪迹天涯”的生活。
  • 学会提问是另一种互动，遇到不懂的话题，不要乱说，可以虚心提问，让对方多讲，做个好的倾听者。 保持开放的心态，尝试并接受新鲜事物，不害怕碰壁，会收获愉快的沟通体验。
  • 美国抽象表现主义艺术大师汉斯·霍夫曼说过：“做减法的能力意味着消除不必要的事，让必要的事发声。”我的理解是做减法的过程，其实是做加法。减去不必要的事，而把时间精力分配给像提升个人修养、丰富人生体验这样真正重要的事。简单的物质生活给了我更多时间去思考、学习和倾听，或许这是我从极简旅行中获得的智慧。
如何更好的运转一个开源项目？Community Leadership Workshop 小记

如何更好的运转一个开源项目？Community Leadership Workshop 小记

发表评论

2023 年，在 DevRel 领域值得我高兴的事情有三：

其一，是今年继续召开的 Dev.Together，又一次和国内从事 DevRel 的小伙伴们一起交流经验，看看大家的生存情况如何，都在做什么事情。

其二，是好友 Richard 翻译的新书：《开发者关系：方法与实践》的出版。作为一个 DevRel 的从业者，开发者的身份能够让我深刻的感知到开发者的痛苦，从而帮助开发者解决问题。但我没有系统的思想，来指导我更加高效的解决问题。

其三，是 Community Leadership Workshop 的召开，可以让我学习到一些过去我不曾思考，或不曾注意到的开源社区和开发者社区问题，帮助我补全自己认知中的空白，更好的服务于开发者。

国内的 DevRel 的从业者们没有太多的资料和经验可以参考，全靠摸索，因此，我也希望通过这个小记，帮你可以看到关于 DevRel 、关于开源社区的一些现状，帮你更好的处理自己的工作。

Community Leadership Workshop 简介

在进行下面具体的内容之前， 先简要介绍一下 Community Leadership Workshop ，这个是在今年的 Apache Con Asia 的会前会，由 @姜宁 组织，@Tison 和 @Richard 参与建设的小规模研讨会，主要介绍他们在企业中从事开源工作和开发者工作的经验，帮助大家更好的理解开源、开发者工作。

从主题上来讲，@姜宁 介绍的主要是企业为什么要做开源；而 Tison 则介绍了他自己在运营一些开源社区过程中的最佳实践（这部分我非常有收获），以及 @Richard 介绍的 DevRel 从业者面临的一些问题。

下面的一些问题，也会围绕着这些主题来介绍，大家可以猜猜哪些内容都是谁讲的。我从 8 小时的分享中，提供出来几个我最有收益的问题，与诸君分享。

从一个问题开始：OpenAI 的 ChatGPT 爆火，应该开源么？

这个问题直击企业开源的根本：为什么要开源？

作为一个开源人，我的下意识觉得 ChatGPT 应该开源，这样可以让他运行的更好，但理智告诉我，OpenAI 不会将 ChatGPT 开源。即使 OpenAI 已经开源了一些能力（比如 Whisper），但对于 OpenAI 来说，目前 ChatGPT 和背后的大模型，依然是其企业营收的重要组成部分。

在大模型是其核心护城墙的时候，他不会选择将其开源，就如同我们看到众多的开源企业，其核心护城河并不是其开源的产物，围绕开源产物的服务才是其真正提供的价值。

而在这部分 @姜宁 也给出了答案：

绝大多数时候，开源的往往不是行业龙头老大，而是行业的第二名，通过开源来实现差异化的竞争：「我可能不是最好的，但我是最好的开源平替，你可以低成本的将其用起来」。就如同 Meta 开源了 LLAMA，通过 LLAMA 来和 OpenAI 竞争。

你的企业到底在开源生态中的生态位是什么？

不同的企业在开源生态当中有不同的生态位，有的企业是开源项目的发起方，比如 Meta 之于 LLAMA，比如 OpenAI 之于 Whipser。有的企业则是开源项目的贡献方，比如 Red Hat 之于 Linux Kernel。

对于项目的发起方来说，他们便是整个开源项目的上游，他们通过开放源码，来在市场中占据自己的一席之地，通过设定不同的 Paywall ，来赚取收益。或者是通过提供官方的 SaaS 服务之类的，来帮助客户解决问题。

而对于项目的贡献方，则是开源生态中的下游，下游的服务一开始可能是基于上游的版本来提供服务，但随着提供的服务不同，下游的企业则需要逐步向上游提供贡献，将自己的代码贡献给上游，以避免自己维护太多的支线版本，造成比较大的维护成本。下游的企业也可以通过逐步贡献，成为一个项目的核心团队，影响项目的发展。

如果你的企业围绕着一个开源项目做事，可以好好想想自己的企业的生态位到底是什么？自己如何为项目贡献、自己如何获取收益？

开源项目的 Default 配置是什么？

我自己也是一些开源项目的维护者，也会试图去围绕开源项目去做一些事情。而在这个过程中，到底哪些是应该做的，应该如何推进，这些问题其实一直我都没有特别成型的理论框架，而这次的 Workshop，在这个问题上给我了很多建议和总结，帮助我更好的去推广项目。

  1. Home Page / 主页是最重要的一件事

很多开发者在开发项目的时候，代码放在 Github 上，就结束了自己的开源工作。殊不知，这只能算是你的代码公开可获得（Source Avaliable），如果你没配置 LICENSE，那就不算开源。

而配置了 LICENSE，也仅仅是解决了你的项目的合规问题。如果你有更高的预期，则需要做更多的工作。这里最重要的便是一个项目首页。项目首页决定了开发者如何找到你的软件和内容。开发者们会通过你的首页来了解最新的更新。

如果你的项目没有首页，那就做一个简单的 Landing Page ，并放在 Github Pages 中，作为你的项目的开始！

  1. 构建社区，而不是拉群

国内因为「私域流量」的存在，大家搞运营喜欢先弄一个微信群，但微信群的问题在于信噪比太低，里面大量重复和无意义的内容。相比之下，建设一个简单的论坛可能是更好的选择。

通过在社区中的引导，你可以让开发者们可以自助交流起来，并尽可能的复用内容，减少内容的重复建设问题。

如果你没有时间和人力去建设一个论坛，那就用 Github 自带的 Discussion 来运行一个论坛吧～

  1. 区分不同类型的开发者

在我之前看来，开发者就是开发者，是不区分类型的。但 Tison 提到，其实开发者也是分类的，有的开发者是核心开发者，有的是集成开发者，有的是应用开发者。

核心开发者往往是因为被你的开源软件的理念所引导而来的，只要软件本身的理念不发生变化，开发者们就会继续使用。

集成开发者则是在不同的系统之间构建集成，他们关注的是你的系统本身的易用性和稳定性，他们往往带着不同的目的来到你的软件当中，你需要通过 Blog、 教程、Workshop 之类的工具，帮助他快速完成集成，从而完成他的业务目标。集成开发者的开发完成后，可以帮助你的业务快速扩张，其集成的特性决定了做的是水管的工作，水管一旦建立，便源源不断的有用户进来。

应用开发者的类型和集成开发者类型差不多，不同的是应用开发者不是构建和现有系统的水管，而是挖出一个新的水池，成本和投入更大，但也能建造出更适合你的业务的水池。也是一个不错的选择。

区分这三种不同类型的开发者，对征下药，可以帮助你有效的完成开发者社区和关系的建立，从而让你事半功倍！

总结

Community Leadership Workshop 的内容实在太多了，对于我来说，每一点都值得细细的分析、拆解和理解，但毕竟文章总是要有尽头的，所以这一篇就先从这里结束啦，后续的内容，且等我拆解成一篇一篇的细节，分享给大家～