对服务设计的思考

本文主要是一份读书笔记，摘抄博文作者在该篇文章中重要的部分。原文链接

简介

为了避免设计的API对于使用者造成困扰，需要满足以下三个原则：

1. 从服务的第一个已发布版本开始实施API版本控制
2. 确保客户的工作负载不会被中断
3. 确保客户在实施新的服务或者集成SDK时，不需要修改原有的代码

从开发者经验开始

一个好的API通常是开始于深思熟虑和良好设计的服务。你的服务需要被定义为一系列容易理解的概念名，只要一提到你的这些概念名就能想起你这个服务。这些抽象概念之间必须有明确的关系。
为了让你能够针对服务内部的概念创建一系列清晰易懂的名称，你需要遵循以下实践：

1. 不要发明花里胡哨的概念或者使用花里胡哨的单词。向非这个领域的专家解释你这个服务下的概念，然后使用相似的措辞来命名这些概念。
2. 不要在名称中使用一次性的词，类似“响应”、“对象”、“负载”这些词。
3. 避免通用名称，名称应该特定化某一个抽象，该名称能够强调出它与其它服务抽象的不同。
4. 从一组同义词中选择一个词并一直使用下去。

在一个设计不佳的服务之上创建一个优雅的API是极其困难的，服务团队和客户将会在数年内忍受这种痛苦， 因此服务团队应该遵循以下原则来满足客户的需求：

1. 构建使用API的应用程序
2. 坚持review并且分享在你的团队中所学习到的知识
3. 获取到客户对于API预览的反馈
4. 思考客户在HTTP操作前和操作后需要写的代码
5. 初始化并读取你的服务需要的数据结构
6. 思考哪些错误可以在运行时修复，而不是在客户的代码中提示必须修复的错误。

预览的目的只要是解决反馈结果的抽象、命名、关系、API操作等一系列问题。可以在预览期间进行重大的改进已改善现如今的体验，使其长期可持续。

专注于Hero Scenarios

首先应该遵循如下的原则：即应该尽可能提供少的功能，随着时间推移，当客户有需求时才提供新的功能。
专注于Hero Scenarios能够减少开发、支持和维护成本。使团队能够更快地调整并达成共识，从而加快交付时间。
针对Hero Scenarios，要满足：

1. 首先需要定义Hero Scenarios，包括抽象、命名和关系然后再去定义操作需要的API
2. 提供示例代码来展示Hero Scenarios
3. 思考你的抽象将怎么样被不同的高级语言所表示
4. 使用至少一种动态语言(python 、js)来开发示例代码，并开发一种静态语言(java、 C#) 来说明你的抽象和高级语言表示
5. 不要增加用户有可能需要的功能到API

从定义API开始

理解你的服务被如何使用并拥有什么样的交互模式：
可以使用OpenAPI来描述服务。

使用预览来进行迭代

在发布你的API版本已投入巨大的设计工作之前，获取用户的反馈，迭代多个预览的版本。这对于V1版本的API尤为重要，因为这直接建立了开发人员与你的服务交互的抽象和模式。
你需要：

1. 编写和测试关于你的客户如何使用API的假设
2. 在第一个GA版本之前发布和评估至少两个预览版本
3. 确定你的客户一起测试的API中的关键场景和设计决策，并要求客户提供反馈并共享相关代码示例。
4. 你可以考虑开发练习的代码，与客户一起开发，观察并学习他们的API使用情况。
5. 你应该在preview阶段总结你所获取到的知识，并与你的团队和API管理团队共享。