软件框架-无绪开发

设计、编写、维护一个稳定的API

1.首先建立一个基本的术语库

描述整个API设计的需求出现缘由，并概述各设计过程的主要目标。

2.设计API时，取一个独一无二的名字，且闻其名知其意（自描述的）

3.设计API的环境要求： 最好做到自己可以处理所需的运行环境

工程师多花点儿时间和精力列出组件所依赖的内容

API就是模块化的代码，模块化程序可以由很多小的独立代码段组成。

这些小的代码段是独立存在，并且唯一标识，通过公开接口的方式供他人使用。

问题： API的库一直动态变化发展的，API是有版本号的，一般都需要向下兼容，如版本5兼容版本4的内容。

A 细心开发各自组件和相应的API

B并且保证兼容性

软件版本的非线性

1               2               3

1.1            1.2

                        1.1.1

需要质量控制部门，

规则一： 如果发布了一个新的版本，那么前一个版本提供的功能和约定，对于新版本应该继续有效。

规则二：如果本组件的外部依赖有改变，那么就需要与其同步调整。

软件版本有两个版本号

标准版本号+实现版本号（通常是一个字符串）

1.1                 Build20170204001

一个管控者，对系统进行检查，保证所有已安装的模块能够保持一致性

多沟通： 如，邮件，电话会议，API自身及相关文档

经验主义编程方式： 先用一个API做个实验，如果不成功，再试一下别的。经验第一，然后才是深入了解。

注意要点：

1.设计的 API 返回值最好不能为空（默认规则）

2.创建一些能够复制和容易修改的示例代码，对第一次试用API的程序员很有帮助。

3.API新版本：增加用户信任，尽量避免破坏兼容性

将一些内容标识为不建议试用，然后明确以文档的形式来告诉用户如何将现有的系统迁移到新组件。

4. 设计的API，在今后的版本中，可能功能不够用或者完全无用了

设计时，需要做好可以随时改变的准备，而且不破坏其用户的现有代码

5.改进API是最重要的内容，可以通过言论自由，先广纳建议，再确定是否添加这项功能，即使第一个版本功能很少，只完成其中之一个的文档和说明，其他内容很丑陋，但没有关系，下一个版本慢慢改进即可。

6.衡量API质量

(1) 漂亮，这是一种优势，但不是唯一标准，因为每个人对漂亮的标准不一样（无法量化）

(2) 易于使用、广为接受且富有成效

(3) 应有详细规则，以确保符合客观标准

(4) 可理解性： 使用API的用户必须能够理解API

API设计者需理解其目标用户普遍具有的知识，在此基础上设计API。如果引入新知识，应是渐进式的，而且要有实例进行帮助使用API 。

(5) 一致性： 一是API版本间保持一致；二是一个API对外提供功能一致。

(6)  可见性：容易找到入口，易于使用

(7)  简单的任务应该有简单的方案：针对不同的API受众应该放到不同API中，这样可以提高程序的可见性

因为某些开发人员只关心某一方面的功能，而其他功能可能会影响使用人员学习

一般情况：一个API分成两个或者多个组成部分，一部分用来针对调用功能的开发人员；一部分应该放在独立的包中，或者有其特定的命名空间，用来方便他人扩展当前的模块功能。

(8) 保护投资：为用户考虑一些，不要破坏现有的代码，保护其用户投入的资源

争取永远以一种兼容的（或者至少是可以预测的）方式来演进API契约。只要有可能出现不兼容的问题，一定要提前调整好对升级需求的期待。

或者很容易编译出新的版本（不严谨，但Linux就是这样做的）

发布第一个版本之前可以修改方法名称或者API结构。一旦发布，尽量不修改

有些调用者： 反射调用内容，有时对新版本失效，原因（这些内容不是公开的API，不承诺兼容性）

API就像恒星，一旦被发现，就永远待在那里

每个协议建立连接时，即使这个协议只是在本地系统上用于内部交互，第一件要做的事情就是一个握手协议，明确一些关键信息，如连接双方的版本，以便他们选择通用的语言进行交流，支持常见情况就可以。

升级时，隐藏相关操作

环境： 系统语言和环境对API是有影响的。

4不断变化的目标 

API发布的版本，仅仅是整个生命周期的起点，判断其是否优秀，需要看多年后，该API是否能依然存在，是否仍然保持的不错。

4.1第一个版本远非完美

第一个版本容易开发、容易发布。每个程序都会存在bug，而且通常情况下修复一个bug的同时可能会引入两个新bug。

为未来做考虑，考虑未来会对API中的那些内容加以改进。两种方式，其一是放弃老版本，重新开始做一套新系统；其二是修正用户提出的问题，强化现有API，保证兼容性。

增量改进：理想情况下，可以做到修正bug，提高程序性能，并提供更漂亮的界面，这一切都不需要用户付出额外的工作。

弃旧创新：可以避免不兼容，并且可以引入创新和更好的功能。问题，使用旧API的用户只能继续沿用旧API，除非重新编写他们的代码，升级到API新版本上。

4.2向后兼容

4.2.1 源代码兼容（原先API接口名称不变即可，而且功能可以增加）

如，API版本1.3兼容版本1.2

即，编写的代码可以同时在老版本和新版本上都编译通过

4.2.2二进制兼容（.h 文件不变，应该就可以达到这种效果）

编译后的老版本代码在执行时，不需要重新编译可以和API新版本进行正常连接执行，称作二进制兼容。

好处：灵活

1.用户可以极大的简化程序的维护、打包和发布工作

2.灵活，用户可以先用老版本API进行开发，最后移植到新版本API即可

要求，API开发人员至少需要了解一些源代码编译后生成的二进制格式

源代码兼容和二进制兼容区别

Java中使用方法优于使用字段

4.2.3功能兼容---阿米巴变形虫效应

各个模块能够按照设计时的目标正确运作

如果一个类库在运行时，不管所引用的是老版本还是新版本的API，其产生的结果完全相同，就是功能兼容。

所以公开的功能或者说行为也都需要考虑兼容性

开发API的人员

1.需要对API要完成的功能有清楚的认识

2.具备良好的即使水平

3.评估用户如何使用这个API（还要想一下这些用户如何来误用API）

4.3面向用例的重要性

站在用户的角度来理解和设计API库。

方法

1.找一些用户，对其进行研究，假想一下用户的用例

2.基于用例设计（有点儿像UML啊。。。）

设计前需要了解

1.为什么要写这样的API

2.API应该长什么样子

3.如何才能完成目标

用户只会对一种情况感到满意： 可以很容易地使用API来完成其工作。

一个用例代表对API一种用户的描述

最新规范，其实都是在程序员的脑袋里，根本没办法检测好还是坏

用例---场景---文档

4.4API设计评审

开始： 所有的API都由一位架构师来开发

--->接下来发现架构师成为了项目的瓶颈（压力山大啊，需要考虑设计、维护API、告诉别人如何使用这个API）

--->改由一个架构师指导一个团队来设计API（刚刚的架构师在团队中选择一些技术最好的人，指导他们设计自己所需的API）

API 就是开发人员与用户之间的一种沟通方式

--->增加一个团队来配合API的开发者对API的评审工作

此时，一旦有一个API需要改的，任何人都可以提交一个改变的请求。其他人则需要在代码正式提交前，进行一次评审，检测新调整的内容是否符合一个优秀API的基本要求。

优秀API规则

用例驱动的API设计：设计API时，要基于一些具体的场景和对API的认识进行抽象分析，最终给出设计。

API设计的一致性：API往往是由多为设计者来完成的，但整个团队中必须能够保持“最佳实践”的一些基本原则。一个接口设计的再好，只要它违反整个团队的一致性，就宁愿退而求其次。

简单明了的API：而且常见的任务应该更容易处理。用例驱动的设计可以通过简单实现场景来验证。

少即是多：一个API对外提供的功能应该只包括用例中说明的功能。这样可以避免出现需要的功能与实际提供的功能两者之间出现的差异。

支持改进：以后也必须能够维护这个类库。如果出现新的需求，或者原作者离开，都不会出现放弃这个类库的情况。

负责API评审的人：向团队成员解释为什么要这样设计API；以及API设计的内容；设计的工作分配给不同的人

4.5一个API的生命周期

API 是沟通交流的工具，双方是API用户和API设计者

API设计：

收集需求

定义问题域

明确用例

再由指定人员来设计API

其他人只是使用这个API，给出建议，列出bug，提出改进意见

API 要有状态，标识当前状态，以便用户了解相应版本是否稳定

如，

Linux 1.2 ，1.4， 1.6 都是稳定版本； 1.1,1.3,1.5 都是不稳定版本 

API分类

1. Private

对于那种仅供内部使用，不公开给外部开发人员使用的模块或者类库

内容：API只包括 环境配置文件以及读取文件的代码

2. Friend

为系统内部其他模块提供相应功能的API

内容：每个模块提供一个Friend列表，明确告诉系统哪些模块可以访问它提供的API