api设计原则

overview

为了规范模块对外提供合理的api，现整理如下原则：

若干原则

作者承责原则

作者对api负责。承担好用、不好用带来的结果。
负责迭代更新。

作者优先原则

作者开发的api应该先满足作者的需求。

不遵从用户优先原则

不以用户为中心开发api。用户能使用的api都是作者已开发的api。
作者决定开发哪些api。用户决定使用哪些api。
用户有使用权。用户可以选择使用或不使用。可以提建议。不可决定api。
此原则是“作者优先原则”的另一种表达。

实用原则

每个api必须可以实现一定功能。

单一原则

每个api只实现一个功能。

符合自然规律原则

这条很重要，但是我不知道如何描述。

避免过度重载原则

每个api可以有一定重载能力。但是不应该过度重载。此原则类似“单一原则”。

一定容错原则

当api收到一些不影响运行的数据或经过处理后可以运行的数据时应该正常返回结果。

严格数据优先原则

当有更严格的数据时应该优先使用此数据。
如：严格的数据类型、限定使用范围的数据。

灵活优先原则

在某同一个实现结果上有多个api控制时，应该使用灵活性更大的数据去实现。

独立优先原则

各api间应该减少重叠控制。尽量做到每个api控制一个功能。减小多个api控制一个功能的情况。

语义原则

命名api时应该做到见文知意。