Lines Matching refs:API

1 # OpenHarmony API 设计规范
7 | v0.1，试运行版 | OpenHarmony API SIG | 2022年11月 | 初版发布 |
11 API是软件实现者提供给使用者在编程界面上的定义，API在很大程度上体现了软件实体的能力范围。
13 同时，API定义的好坏极大影响了使用者的体验。
15 为了保障OpenHarmony生态健康发展，保证开发者使用体验，现制定OpenHarmony API设计规范。
19 OpenHarmony API主要包含了对应用开放的外部API，以及系统实现部分的内部API。
21 本设计规范主要用以约束以下API（不区分编程语言）：
23 * OpenHarmony Public API
24 * OpenHarmony System API
26 关于OpenHarmony API的分类，请参见[《OpenHarmony API治理章程》](https://gitee.com/openharmony/docs/blob/master/zh-c…
35 * **可预测** （Predictable）：API应当始终一致的按照接口的定义完成使命。如果接口定义中不包含出错和异常的情况，那么这个API被调用任意多遍，都不应该发生任何异常。当然，如果实际情…
37 除此之外，API的设计还应该注意以下几点：
39 * **API的稳定性和一致性是最重要的，API并非越多越好。**
40 * **API命名应当容易理解，API命名并非越短越好。**
41 * **API应当做好封装和抽象，并非暴露的信息或者能力越多越好。**
43 从开发者使用API的阶段上来看，API应当做到：
56 ## API设计概述
60 从整体上来看，本规范将API规范分成**发布前评审规范**和**发布后评价**两个部分。
62 * **发布前评审规范** ：是对于API的最基本要求，所有API必须满足这些要求才能通过评审。
63 * **发布后评价** ：尽管在发布前已经做了很多的规则要求。但是仍然不能保证API是完美的。因此，API发布后仍然要保持对API的关注。发布后的审视将影响对API提供者的评价。
65 以下是所有的API设计规则的罗列，以供快速索引，详细的说明在后文中展开。
67 每一个OpenHarmony API提供者都应该熟悉以下规则。
108 * API资料
138   * 规则54：保证API之间正交
146 任何设计都应该考虑易用性。对于OpenHarmony API来说，易用性需要考虑以下几个方面：
152 API的定义首先应当满足所属项目的编码规约，例如：大小写的定义、下划线、连字符规则、前缀规则等。
163 API命名只允许使用英语。通常，类的名称是名词，例如：`XXXManager`，`XXXService`，`XXXAnimation`等。函数通常是动词或动宾结构，例如：`start()`，`cre…
186 但在API命名中，应当注意对仗词的使用。
398 一个 API 应当尽量只做一件事情，尽可能保持单一核心的职责。例如：
429 每个特性或者能力在规划时，需考虑到功能的完备性。不应当出现：在支持的范围内，某个流程中断，或者某个选项缺失的情况发生。API设计者应当做好足够的验证和推演。
446 1. API调用的返回仅包含必要的内容， 避免携带额外信息。
447 2. API调用不允许获取、收集用户个人数据， 除非通过用户权限管控、由用户授权同意。
448 3. API涉及跨应用调用时，如涉及个人数据向被调用者的披露，由调用方在隐私声明中说明披露的数据类型、数据接收者和数据使用目的。
449 4. API涉及到用户敏感数据（如电话、通讯录、媒体等）访问时，需要使用system picker的机制，禁止API通过申请敏感权限方式访问。
450 5. API开放禁止捆绑与所开放能力不相关的功能。
454 保证所有的接口线程安全需要付出很大的代价（程序复杂度、性能影响），因此OpenHarmony API不必要求所有接口线程安全。只需根据需要选择即可。
478 并且，API要明确客户端调用失败后，能够发起重试的最大次数。
498 当然，有一些API只在某些特定设备上才有，例如：
503 这种情况，请参考[《SysCap使用指南》](../application-dev/reference/syscap.md)，来标定API的适用范围。
536 在一些 API 设计的场景中，即使命名已经做到准确，但在有些情况下仍然可能碰到不一致的场景。比如，API 中经常会看到 picture 和 image、path 和 url 混用的情况，这两组词的意…
600 API 变更的成本非常高，在设计之初就应该做尽可能完备的考虑。但是API变更始终是系统发展过程中不可避免的。
602 API 变更要保证向后兼容原则，API 变更后，废弃的 API 要在源码和文档中显著标识 `deprecated`，并引导开发者使用变更后 API 。
604 废弃的 API 要保证其功能仍然可用，至少保留5个版本。5个版本后，在充分告知开发者，并给与充分的时间供开发者修改后，可予以删除。
610 以C++接口为例，常见破坏二进制兼容的API变更包括：
612 1. 任何API元素删除
619 由于C接口相比C++接口在二进制兼容性上有天然的优势，所以OpenHarmony的Native API推荐使用C接口定义。
621 ### API资料
623 API的很多信息需要通过文档和资料进行说明，因此，配套的这些内容也应当做好质量管理。
649 对于API的每一个参数，都应该说明清楚。例如：
676 元信息描述了API自身的基本信息。工具和SDK会利用这个信息进行相应的处理，例如：针对已经废弃的接口会给出警告提示。
680 API的说明资料，在风格和样式上应当保持一致。例如，文字的加粗，资料图片的配色等。
697 这里每一层所要考虑的概念和要处理的问题都是不一样的，请仔细思考你提供的API是在哪一个层次上。
707 接口的英文是Interface，这个词还有界面的意思。操作系统提供给开发者的接口并不仅仅是编程接口。任何公开给开发者的机制，都是API的一部分。
719 1. 应及时响应，避免调用者等待；如果API调用执行时间过长应设计为异步方式。
722 4. 对使用资源的API调用需要能及时释放资源，异常场景具备容错机制，保障资源及时释放。
742 所以，对于一个OpenHarmony API，都要求做到以下几点：
744 1. 新增API必须同步交付API自动化测试用例，用例100%覆盖API接口。
760 尽管在API发布前已经做了多方面规则约束，但总可能还有一些问题在开发者使用之后才能发现。
762 即便是这样，但并不意味着在设计API之初不需要考虑这些问题。
776 设计出能保证长期稳定，持续兼容的接口是每个API设计者应当追求的目标。
800 特别的，如果某些接口（无论在何种情况下）一旦调用就可以使用系统崩溃，或者进入不能工作的场景，或者能够窃取用户数据，这是绝对不允许的。这就要求API的设计者从API被调用的所有可能都场景上进行考虑，避…
832 * **规则54：保证API之间正交**
846 尽管API在正式发布之前，会经过试用阶段，但考虑到试用时间和试用范围是有限的，实际上无法保证能避免所有问题。
852 * 希望提供更多API来满足目前不能实现的功能，这种情况可以将需求导入到下个版本的规划中。
853 * 反馈API的行为与文档描述不一致，这通常是缺陷，应当尽快修复。如果是文档的问题，也应当尽快修改。
854 * 反馈接口设计不合理，可能是命名或者参数设置存在问题，这种情况就需要考虑API废弃同时用新API代替。
856 在一些情况下，可能要变更已经发布的API行为。这种情况下，应当要注意：行为变化只能发生在新开发的应用上，对于已经发布的应用，不能产生行为变化。API提供者可以根据应用的目标API版本来进行判断。
858 在最坏的情况下，需要将既存API废弃，提供新的API代替。