前言

相信每个开发者对于API都不会陌生，最近几十年，随着软件工程行业的发展，自造轮子的情况已经少之又少，每天的工作都不可避免的要用到其他模块或提供提供的API，也有不少人要开发API给其他人用。这篇文章呢就是以面食窗口为案例来介绍API设计的一些原则和思路，希望能帮到大家。
故事就从下面这碗香辣牛肉面开始。

API的意义

API设计非常普遍
API设计影响范围广泛
API设计影响持续时间长
API设计技巧抽象难以理解

面食窗口的 API演进

假设管理食堂的面食窗口，
为大家提供面食服务就相当于为大家提供API服务，其他人扮演着客户端的角色，通过API向你获取面
请的是祖传刀削面和汤底的师傅，这个是你独特的竞争优势
你只提供香辣牛肉刀削面作为故事的开始。

第一天，生意开始

策略：
统一销售牛肉刀削面
API:
http://localhost/api/v1/noodles

客户端：来一碗刀削面
客户端：来一碗刀削面
客户端：来一碗刀削面，不要香菜
服务端：500，我们这都有香菜，不能不加

新的业务需求引发了接口变更的需求
接口发生变更时尽量向后兼容，新增而不是修改接口

第二天，生意更好了

策略：
销售牛肉刀削面,单独不要香菜的接口
API:
http://localhost/api/v1/noodlesWithoutXiangcai
http://localhost/api/v1/noodles

客户端：来一碗刀削面，要香菜
客户端：来一碗刀削面，不要香菜
客户端：来一碗刀削面，不要香菜
客户端：来一碗刀削面，不要辣椒
服务端：500，我们这都有辣椒，不能不加
客户端：来一碗刀削面，要宽的
服务端：500，我们这都是细的，

当不得不调整参数时应建立新的接口

第五天，一切都看起来不错

策略：
销售牛肉刀削面,可以配置是否要香菜，是否辣，是否是宽的
API:
@Warning
http://localhost/api/v1/noodlesWithoutXiangcai
@Warning
http://localhost/api/v1/noodleshttp://localhost/api/v1/noodles?xiangcai=1&hot=1&suancai=0&huasheng=1&......

业务场景
客户端：来一碗刀削面，要香菜要辣不要酸菜不要花生
客户端：来一碗刀削面，不要香菜要辣不要酸菜不要花生，
客户端：来一碗刀削面，不要香菜要辣要花生不要酸菜
客户端：来一碗刀削面
服务端：500，条件不足

客户端需要了解不必要的业务细节
改进：封装己方核心业务逻辑，提供工具和可组合使用的接口，将业务灵活性交给客户端

第十五天，生活真美好

策略：
3步法定制：
1.获取默认调料
2.定制口味
3.根据口味获取面食
API:
@Warning
http://localhost/api/v1/noodlesWithoutXiangcai
@Warning
http://localhost/api/v1/noodles
@Warning
http://localhost/api/v1/noodles?xiangcai=1&hot=1&suancai=0&huasheng=1&......
http://localhost/api/v1/flavoringTemplate
http://localhost/api/v1/noodles?mode=宽&flavoring=gg

客户端：来一碗默认的刀削面
服务端：好的

客户端：都有哪些调料
服务端：这个就是调料包
客户端：这个是我要的面的口味（组合调料包），给我我要的面，宽的
服务端：ok，稍等

最终状态

面食窗口不但提供刀削面还提供粉等类似的食物。
业务流程：
1.用户向框口提交基本要求，什么面，大小碗
2.窗口将面交给用户，同时提供给用户一个自助区域
3.用户到自助区域内添加自己喜欢的调料
4.口味调整好后，可根据需要再把面交给窗口添加独家汤底

至于API情况大家可以自己想想该怎么实现。

总结

在这篇文章中，我们通过面食窗口的服务模式的变更说明了API设计的注意事项和主要原则
下面简单列一下API设计和开发基本原则：

新增而不修改
封装核心业务逻辑
API名副其实
每个API只做自己应该做的事
服务端尽量不存储状态
接口尽量少
支持组合使用

此外还有就是API的版本管理要注意，不是说废弃就能废弃的。

面食窗口的API设计之道相关推荐

从达标到卓越 —— API 设计之道
摘要: 新技术层出不穷,长江后浪推前浪.在浪潮褪去后,能留下来的,是一些经典的设计思想. 在前端界,以前有远近闻名的 jQuery,近来有声名鹊起的 Vue.js.这两者叫好又叫座的原因固然有很多,但 ...
《iOS应用软件设计之道》—— 3.1　流向：从一个画面到另一个画面
本节书摘来自华章出版社<iOS应用软件设计之道>一书中的第3章,第3.1节,作者:(美)William Van Hecke ,更多章节内容可以访问云栖社区"华章计算机" ...
微服务API设计的实践与思考总结
点击上方"朱小厮的博客",选择"设为星标" 后台回复"书",获取后台回复"k8s",可领取k8s资料随着微服务的越来越 ...
service 层拼接的html 代码如何直接返回_代码分层的设计之道
分层思想,是应用系统最常见的一种架构模式,我们会将系统横向切割,根据业务职责划分.MVC 三层架构就是非常典型架构模式,划分的目的是规划软件系统的逻辑结构便于开发维护.MVC:英文即 Model-Vi ...
mvc三层架构_Java架构-代码分层的设计之道
分层思想,是应用系统最常见的一种架构模式,我们会将系统横向切割,根据业务职责划分.MVC 三层架构就是非常典型架构模式,划分的目的是规划软件系统的逻辑结构便于开发维护.MVC:英文即 Model-Vi ...
C++ API 设计 06 第一章简介
第一章简介 1.1 应用程序编程接口是什么? 应用程序编程接口(API)提供对问题的一个抽象,并说明客户端如何与实现这个问题的解决方案的软件组件来进行交互. 这些组件本身通常作为一个软件库发布,允许 ...
QQ API设计说明书
QQ API设计说明书深圳腾讯计算机系统有限公司目录一.引言. 3 1.1 编写目的... 3 1.2 更新时间... 3 二.总体设计. 3 三.注册的系统消息 ...
C++ API 设计 07 第二章
第二章品质本章的目标是回答下面的问题:一个良好的API需要什么样的品质?大多数开发人员都同意,一个良好的API应该设计得很优雅,而且仍然非常容易使用.它应该在后台运行且使用起来让你觉得很惬意.这些 ...
API设计中性能提升的10个建议
[引子]节前的时候, 一好友约我聊一聊API 的设计.当时觉得仿佛有万语千言,但我又难以脱口而出1.2.3.原来,即便是工作的日常,也缺乏一个系统性的思考和整理.API的设计涉及到的方面很多, 分类是 ...

面食窗口的API设计之道

前言