接口的设计是必须跟随版本管理走的。
版本管理基础
设计制作软件的时候，应当按照规范的方式设计版本标签，请参考下图。 
概述
版本管理 并不需要非常死板，但是必须要有版本管理意识，通过 合理设计版本号 ，使协作开发人员可以判断你对程序软件的改动大小，并配合你的开发策略跟进开发。
开发人员改代码时，部分代码的改动是为了 修 bug，部分代码的改动是为了 新添功能，而还有的时候则是重构代码、把旧代码全部删了重新使用新的技术或者策略进行开发。在不同的改动情况下，版本号的递增方式需要经过妥善考虑后进行递增，以便于你的软件的使用者/对接者能够顺利对接你的软件。
如何合理设计版本号
此处例举我设计版本号时惯用的一套规则。
发布号的使用
开发过程中，软件已经可以使用，可能有 bug，但至少代码已经 封装好了、粗略调试可用、等待联调时，可打 Tag。每发布时，Tag 的发布号 递增。
接口若发生变化，但是 仍能兼容旧的接口调用方式 时，可以使用发布号的递增。但如果接口不再兼容现有的接口调用方式时则需要增加小版本号。 
根据提交历史，在完成当前需求、发布软件时，打 Tag，并递增发布号。
改到一半、并不能运行的软件 不打 Tag。在代码改完、能 调试运行时，打 Tag。
小版本号的使用
当软件接口发生明显变化，或者软件设计策略发生变化后，发布新的软件时，使小版本号递增，并使 发布号归零。
此处描述的设计策略包括 算法 的改动、单线程/多线程运行策略 的改动、是否使用 额外资源比如GPU或大量内存、磁盘容量等 进行计算的改动等。
总结一下通常情况下在此时升高小版本号：
- 软件输出的数据格式发生改变
- 比如输出的 JSON 文件的结构发生改变，旧的读 JSON 方式无法兼容。
- 现有接口发生变化，不再兼容现有调用方式
- 比如 删除 了接口函数。
- 改变了接口函数的 参数 或 返回值。
- 对于命令行程序，删除或改动命令行参数对应的软件行为。
- 接口设计模式大幅变化，比如从 调用子过程方式进行接口调用变为 接口类继承、实现接口类成员函数。
- 完全新增一套新接口
- 比如新增 Web API。
- 在已有 调用子过程方式实现功能的基础上，新添一整套的 接口类方式接口。
- 一个 DLL 程序，原本只提供了纯 C 语言接口，改动后新增了针对 Java 的接口函数，可用 Java 类封装。
- 一个只能通过读写本地 文件来工作的软件变为可以与其它软件直接 通讯交换文件内容。
- 软件行为发生明显变化
- 比如本来是执行完成任务后就 立即结束的软件变为内存 驻留待命的软件。
- 从完全不会产生临时文件的软件变为会 产生临时文件的软件。
- 从不需要额外的权限变为有时 需要额外的权限提升的软件。
- 单线程软件变为 多线程软件。
- 纯本地可运行软件变为 需要联网调用某 Web 接口后才能运行的软件。
- 软件若需要按照 特定结构来使用文件系统时，文件目录结构发生变化。
- 软件兼容性发生变化
- 比如增加/减少了 系统软件依赖。
- 小幅度改变对 硬件性能的最低要求。
- 增加/减少对 网络的依赖。
- 增加/减少对系统已安装 字体的依赖。
- 软件增加了新功能
- 比如某图像压缩软件被设计为既可以压缩图像也可以压缩视频。
- 软件使用的系统资源发生明显变化。
- 比如从只使用 CPU 变为同时使用 CPU 和 GPU 的计算方式。
基本上，小版本号主要用于 明确当前软件的执行时的各项前提要求。从系统设备资源的使用到接口依赖的需求。
多端对接时，接口的调用需按照接口对应的版本来设计。
大版本号的使用
当软件发生了 大幅改动，尤其是发生了重构，许多 旧代码被删除，然后使用 新的技术或更换了 开发策略进行开发，或整个软件与其配套服务 逻辑框架发生变化时，软件发生大版本号的改动。
- 典型例子1：Java 编程语言为了提升其功能和性能，方便性和安全性，对系统库和语法进行了改变，在此时 Java 语言的版本号进行 大版本号升级。使用 Java8 进行开发，和使用 Java9 进行开发的时候，开发者可以明显察觉 Java8 与 Java9 的差异，并且部分旧的 Java8 写法不再能在 Java9 里面使用。大版本号的变化，可以让使用者/对接者能够明确察觉到 软件使用策略的大幅变化，并且会专门研读文档中描述 Java8 与 Java9 之间差异的部分，来更好地使用软件。
- 典型例子2：Python 编程语言在发展过程中不断增加新特性、改善其书写舒适度和代码美观度，不断增加小版本号，比如 Python2.6 经过改进后变为 Python 2.7，增加了新的语法特性。但是， Python2 在发展的过程中，人们发现一个无论如何也无法逃避的事实：现有的语法设计本身对 Python 语言的发展有较大的限制，比如：在面向对象编程语言的思维逻辑下，Python2 的语法并不完全尊重面向对象编程的思维逻辑，语法中有相当大的一部分内容不符合面向对象编程。于是，Python 的开发者们 重新设计了这款编程语言的语法逻辑，Python3 就诞生了。它的 定位并没有明显的改变：Python 的定位是 专用于偷懒的舒适的脚本语言。但是它的使用方式发生了较大的变化：整套语法都重新设计了。Python2 的使用者需要重新学习新的 Python3 的语法后才能使用 Python3，而任何一个使用 CMD/shell/bash 的苦难者在想要改变现状的时候，会发现不论是 Python2 还是 Python3 从定位上来说都很符合他的需求，但是因为 Python3 的大版本号是3，Python2 的大版本号是2，将来的趋势一定是 Python3 会变得越来越好，并且 Python3 的语法设计更加合理，是较为完备的面向对象编程语言，而 Python2 则不再得到维护，淹没于历史的海洋。于是初学者会选择 Python3 来学习使用，并使 Python3 的社区得到更好的发展，最终使 Python 编程语言可以成功从 Python2 时代过渡到 Python3 时代。
不过一般情况下一个软件开发者也可以 不使用大版本号，而是直接 开新坑，建立新工程，重新取名字，并找来完全不同的另一套依赖库，以及人马，针对某个业务场景进行全面优化。
接口设计规范
接口设计与软件版本挂钩。接口决定开发者之间的协作方式。协同开发时，不同的开发者之间必须约定好接口。
1. 设计接口时：需尽量多考虑接口会被以什么样的方式使用
做好接口参数合理性检查
- 你的接口的使用者不一定是你的同事，他也可以是入侵进来的黑客/你的敌人/你的测试人员。
- 当你的接口被人不慎进行错误调用时，你的程序不会因此崩溃/发生任何非设计性的行为（术语：Robust， 鲁棒性，或称 肉棒性）。
公私分明：做好隔离，避免调用者越过接口使用你的私有内部数据
- 你在进行你自己的内部开发的时候，你会有需要频繁改动的代码。这部分代码做成私有，禁止外部直接访问。
- 如果能隐藏私有的部分使其不可见，是上策。
- 比如 C 语言使用结构体
struct 来设计概念上的对象时，你可以用一个 void* internal; 成员指向你程序内部工作时需要用到的数据。
- 如果不能隐藏私有部分，做好标记，让使用者知道这部分的数据别碰。
- 比如 Python 可以在私有的函数和变量名字前面添加下划线
_，使其在外部不能被直接使用。
- 比如 C++/C#/Java 可以使用
private 关键字。
- 不希望被外界改动的数据需做成 只读属性。
- C++ 没有 只读属性，因此 C++ 在这个地方通过设计
GetXxxxx() 这样的函数来获取数据。
- C 语言同上。合理设计 getter/setter
- Java 可以使用
final 关键字，但这会导致数据你在内部也无法改动。此时也靠使用 getter。
充分详细设计报错逻辑：用好异常机制或错误码机制，使你的调用者可以判断接口是否正常工作。
- C++/C#/Java 设计接口时，一定要明确你会抛出的 所有的异常种类，便于调用者根据不同的异常类型进行处理。
- C++ 的
std::map 或者 std:unordered_map 的 at() 方法在 Key 无效的时候并不会自动提示 Key 的值。需要做好封装，自己提示 Key 的值用于排错。
- 使用错误码方式设计接口时，应尽量提供 错误描述字符串，便于打日志排查错误。
- 命令行程序明确返回值、正常内容输出到 STDOUT、报错内容输出到 STDERR，程序正常执行时应返回
0 作为 ExitCode，参数错误时返回 1，程序遇到问题而报错退出时返回 -1，以便于你的程序可集成到 bash/Python 脚本等。
- 调用命令行程序时应当读取命令行程序输出的所有内容包括 ExitCode、STDOUT 和 STDERR。
- Java 调用命令行程序时应同时读取
getInputStream() 和 getErrorStream() 的数据。
编写文档：描述清楚你希望别人如何使用你的接口。
- 文档一定要包含 接口的版本，针对不同版本的接口需要编写 不同的文档。
- 具体描述接口参数如何传递、如何使用返回值、什么样的参数有效、什么样的参数会导致错误。
- 具体描述接口内可能发生的功能实现行为，尤其是以下几点：
- 能否多线程调用，是否需要调用者自己上锁。
- 你内部是否使用了锁。
- 你大致是如何实现你的功能的。让调用者心里有个数。注意不能明确提到接口内部 私有部分的使用。
- 抛出异常的原因，以及所有的异常种类。
- 如何排错，以及排错案例。
编写 Demo 例程，让调用者可以 CV 你的代码来调用你的接口。
Demo 例程也应当包含充分的文档，去描述为何接口要如此调用。
2. 发布接口前三思：需尽量全面考虑其是否会影响后续的开发
接口一旦明确下来，对接的开发者们各自将针对接口进行自己的软件开发。接口功能提供者提供具体的功能实现，而接口功能的调用者则按照 接口文档对接口进行调用。
适当确保灵活性，留好所有可能需要的参数的入口
一定要留好所有的坑点，避免常量、字段数值写死，并保留余地使 接口在不发生变化时你可以给你的程序 添加新的功能或者除错。
发布前，尽量和对接的开发者进行协商，了解对方在使用时 可能的需求。留好你的坑位，在这些需求真正到来时，你可以减少对接口的改动。
注：灵活性不能太高，一旦高于接口对调用者的约束，你的接口设计将 **形同虚设。
3. 尽量避免对接口的设计进行改变
不到万不得已，不应改变现有接口的功能。 可以增加新的接口，但是不能减少旧的接口。
- 如果某接口函数的内部实现已经是不需要的了，则你依然无论如何都要提供这个函数，并使其内部没有任何行为，以确保你的接口符合调用者所理解的逻辑。
一旦发生接口变动，需要和所有对接者进行及时的沟通，并及时 更新接口文档以便于对接者查阅。
接口变动影响软件对接时，应当更新软件的 小版本号以体现 软件运行需求的明显变化。
| 
|Archiver|小黑屋|技术宅的结界
( 滇ICP备16008837号 )|网站地图
发表于 2023-11-24 12:05:20
发表于 2024-1-24 23:07:21