提交 3fb5179f 编写于 作者: H huawei_qiangbo

Add OpenHarmony-API-quality.md and update glossary.md

Signed-off-by: Nhuawei_qiangbo <qiangbo2@huawei.com>
上级 436fd08f
......@@ -2,7 +2,7 @@
## 背景
* API类型:[Public API | Test API| HDI]
* API类型:[Public API | System API |Test API| HDI]
* API需求来源:
* API使用场景:
* API所属子系统:
......
......@@ -28,7 +28,7 @@ OpenHarmony软件栈中包含了多个角色,因此API也分作多种类型。
各类型API说明如下:
* Public API:OpenHarmony对所有应用开发者公开的API。
* Test API:测试专用的API,供开发者使用。
* Test API:测试专用的API,仅在测试阶段使用。
* System API:提供给系统特权应用使用的API,普通应用无法使用。
* HDI:描述硬件能力的接口。
* Driver API:提供给驱动开发者使用的接口。
......@@ -41,6 +41,7 @@ OpenHarmony的目标是构建面向万物互联时代的新一代操作系统,
* C/C++
* JavaScript
* TypeScript
* ArkTS
本章程所描述的内容与编程语言无关。即:在不违反编程语言要求的情况下,API不分编程语言都要遵守章程的要求。
......@@ -66,7 +67,7 @@ API评审流程如下:
1. API评审申请、代码提交(Owner:Contributor),所有涉及API新增或变更需同步提交相应的API评审文档,详细说明API的需求来源、场景与使用方法、权限设计、隐私保护澄清等,详见后面的API评审申请要素。为避免后续的返工,Contributor可以在正式的API评审申请、代码提交之前,先通过邮件方式将API设计文档提交Committer、领域SIG、API SIG等相关人员预审。
1. 代码评审(Owner:Committer),代码评审和API预审,涉及API提交Code Review通过后,还需要进一步领域SIG评审。如果单次提交同时涉及多个领域的API新增或变更,相应的API评审申请和代码需要同时提交给相关领域的Committer评审,只有所有对应领域的Committer都完成CodeReview后才能进入下一评审环节。
1. API评审(Owner:领域SIG),新增API相关的代码提交评审,领域SIG评审通过即可代码合入;变更API相关的代码提交,领域SIG评审通过后,还需要进一步提交API SIG。如果单次提交同时涉及多个领域的API新增,相应的API评审申请和代码需要同时提交给相关领域的SIG评审,只需一个领域SIG评审通过即可代码合入。如果单次提交同时涉及多个领域的API变更,相应的API评审申请和代码需要同时提交给相关领域的SIG评审,只有所有对应领域的SIG都要评审通过才能进入下一评审环节。
1. API变更评审(Owner:API SIG),变更API相关的代码提交评审,评审通过即可码。
1. API变更评审(Owner:API SIG),变更API相关的代码提交评审,评审通过即可码。
1. 评审完成。
### API评审申请要素
......@@ -74,88 +75,24 @@ API评审流程如下:
如果涉及API新增或变更需同步提交相应的API评审文档。API评审文档使用[《OpenHarmony API 评审模板》](API-Review-Template.md)描述。
针对新增API,需要包含如下要素:
1. 需求来源与使用场景(必须)
1. API现状与差距分析,说明API新增或变更的必要性(必须)
1. API原型设计与使用方法说明(必须);必要时,可以进一步包含相应的使用样例(可选)
1. API权限设计(必须)
1. API隐私保护方案与要求满足情况澄清(必须)
1. 提交代码的同时提交相应的API参考(必须);必要时,可同步提交相应的开发者指南文档(可选)
1. 兼容性/性能/功耗/可靠性/测试等相关情况说明(可选,如不满足本章程 “API设计要求”,则必须包含相关说明)。
1. (必选)需求来源与使用场景
1. (必选)API现状与差距分析,说明API新增或变更的必要性
1. (可选)API原型设计与使用方法说明(必须);必要时,可以进一步包含相应的使用样例
1. (必选)API权限设计
1. (必选)API隐私保护方案与要求满足情况澄清
1. (可选)提交代码的同时提交相应的API参考(必须);必要时,可同步提交相应的开发者指南文档
1. (可选)兼容性/性能/功耗/可靠性/测试等相关情况说明(如不满足本章程 “API设计要求”,则必须包含相关说明)。
针对变更API,需要额外包含如下要素:
1. 针对老接口的处理方式(废弃、隐藏或彻底删除)以及对使用老SDK开发应用的兼容措施(必须);
2. 变更影响、替代接口和相应的应用适配方案(必须)。
3. 刷新ChangeLog(必须) 和 API-diff文档(涉及JS/Native API变更,必须)。
## API设计要求
### 一致性要求
1. 概念一致性:基于场景的业务模型抽象,形成OpenHarmony的连贯、一致、自恰的用户程序模型和业务概念。
1. 术语一致性:相应的业务术语必须采用统一名词,不允许使用多个语意接近的名词表示同一个业务对象;同样地,为了避免产生混淆,也不允许针对不同的业务对象使用相同的名词或语言接近的名词。
1. 操作一致性:相同的操作动作必须采用同一动词。
1. 参数顺序一致性:相同参数/参数序列在多个API中的位置和顺序保持一致。
1. 机制及算法一致性:通信机制、调用模式、认证机制、加密算法等保持一致。
1. 帮助、Demo、模板风格一致性:排版、用法等保持一致。
### 易用性要求
以“能力使用者”视角,而不是“能力提供者”视角设计API:
1. 可理解:API命名和功能特性必须容易理解。
1. 易使用:提供简单易用的API,减少API之间不必要的耦合,避免多个无之间关联关系API之间调用顺序的依赖,尽可能使调用者优雅,尽量避免使用单一功能时必须同时组合调用多个包/模块或类中的多方法才能实现。
1. 避免误导:提供使用者期望的能力,避免误导,减少误用。
1. 提供必要的API文档。
### 命名要求
1. 能清晰的表达意图:使用完整的描述性的单词。
1. 避免造成误导:有误导的名字比表达不清的名字还要有危害性。
1. 词义清晰明了,避免使用info,data,object等一般意义的词。
1. 作用域越大,命名应越精确。
1. 不用或少用缩写,业界通用术语遵从行业习惯允许使用缩写。
1. 包名/模块名/命名空间前缀约定:
1. JS API 统一模块名:@ohos.\*
2. Native API 统一命名空间:namespace OHOS.\*
3. 引用外部开源代码的,可以保留原包名/模块名/命名空间,也可以按照上述规则对包名统一进行替换。
1. 包名/模块名/命名空间最短不少于2段,最长不超过4段;每一段建议使用一个单词,最长不超过2个单词。
1. 类名、方法名/函数名、成员变量、变量名最多不超过4个单词。
### 权限控制要求
1. 完备性原则:一切穿透应用沙箱的行为都需考虑使用权限来管控。
1. 最优粒度原则:一个权限只保护一类对象;一个接口仅需申请一个权限即可访问。
1. 清晰完整原则:权限定义中必须清晰说明保护对象、开放范围、敏感级别。
1. 最小开放原则:一个权限仅对确有正当业务需求的应用开放,开放控制可通过权限来实现。
### 隐私保护要求
1. API调用的返回仅包含必要的内容, 避免携带额外信息。
1. API调用不允许获取、手机用户个人数据, 除非通过用户权限管控、由用户授权同意。
1. API涉及跨应用调用时,如涉及个人数据向被调用者的披露,由调用方在隐私声明中说明披露的数据类型、数据接收者和数据使用目的。
1. API涉及到用户敏感数据(如电话、通讯录、媒体等)访问时,需要使用system picker的机制,禁止API通过申请敏感权限方式访问。
1. API开放禁止捆绑与所开放能力不相关的功能。
### 文档化要求
1. API参考采用英文方式交付。
1. 模块/包模块的API参考必须包括简要描述和详细描述。
1. 类、方法、“Interface”、枚举或成员变量的API参考必须包括简要描述。
1. 类、方法、“Interface”、枚举或成员变量的API参考可选包括详细描述。
1. 方法、“Interface”的API参考必须包括所有入参的参数描述。
1. 如果方法或“Interface”有返回值,则API参考必须包含返回值描述。
1. 如果执行过程中可能抛出异常,则API参数必须包含相关的异常描述。
1. 必须包含API的起始版本号(使用@since注释标记)。
1. 可选包括本模块或类自己的版本号(使用@version注释标记)。
1. 涉及API变更(不兼容),必须同步交付API-Diff和ChangeLog文档。
### 兼容性要求
1. 按严格程度从高到低,API兼容要求包括:契约兼容 > 二进制兼容 > 源码兼容。
1. 源码兼容:指版本演进后,开发者已有的源代码可正常编译通过。
1. 二进制兼容:指版本演进后,开发者已有程序不用重新编译可正常链接、运行。
1. 契约兼容:也称语义兼容,指版本演进后,开发者原有程序行为不发生变化。
1. OpenHarmony API后向兼容必须满足二进制兼容要求,例外情况需要通过API SIG评审并经过PMC批准。常见破坏二进制兼容的API变更包括:
1. 任何API元素删除;
1. 降低方法的可见性,例如protected修改为了private,或者public修改为protected。
1. 类类型发生变化,例如抽象类变更为非抽象类,或者接口类(“Interface”)变更为非接口类。
1. 方法原型发生变化,例如返回值类型修改,或入参顺序或入参类型发生变化。
1. 成员final/static等属性发生变化,例如非final成员变成final,或者非static的成员变成static。
1. 禁止“原型相同、功能不兼容”的API修改,可受限使用“废弃old-api、新增new-api”的方式进行修改。
1. 根据发布类型不同,API的生命周期和兼容性要求:
## API的生命周期和兼容性要求
OpenHarmony API会以API version的形式逐步演进。每个版本会经历如下图的发布周期。
不同周期的API其兼容性要求如下所述:
![](figures/API-Lifecycle.png)
......@@ -173,33 +110,6 @@ API评审流程如下:
1. 提供可替代接口。
1. 废弃API至少保留5个API Version版本(对废弃5个API Version的API可以彻底删除,不再支持)。
### 性能要求
1. 应及时响应,避免调用者等待;如果API调用执行时间过长应设计为异步方式。
2. 应关注API调用时机、调用频次对RAM占用的影响。
3. 应关注API调用时机、调用频次对功耗的影响。
4. 对使用资源的API调用需要能及时释放资源,异常场景具备容错机制,保障资源及时释放。
### 功耗要求
1. 针对API调用时机、调用频次对功耗的影响做评估,有影响进行相关设计。
2. 版本演进过程中,功耗不劣化。
### 可靠性要求
1. API不能因为外部输入(输入参数、系统状态、外部数据等)或者内部状态、数据异常而崩溃,应该返回确定的错误码或者抛出预定义的异常。
2. API应明确调用是同步还是异步调用,若是同步调用,应明确超时上限或者允许调用者设置超时时间,避免调用卡死导致业务无响应。
3. API务必支持多线程重入。
4. 满足幂等性要求,相同业务含义的请求API调用一次或多次重试总能获得相同的效果(API调用依赖外部资源的变化除外)。针对可重入的API调用实现内部应尽量避免引入时变因素,如系统tick、静态变量、没有互斥保护的全局变量等;针对同一客户端的多次重复调用,可以使用contextID、clientToken、sequenceNo等作为调用入参。
5. API内部创建对象的生命周期要闭合,避免对象资源泄漏。
6. API要明确客户端调用失败后,能够发起重试的最大次数。
### 测试要求
1. 新增API必须同步交付API自动化测试用例,用例100%覆盖API接口。
2. 用例场景单一,单条用例覆盖接口单个功能场景,简化单条用例代码逻辑。
3. 用例执行高效,每条用例执行时间控制在毫秒级。
4. 用例执行全自动化:接口用例需要达成100%自动化。
5. 用例有效性:用户要求必须存在断言,且不能仅是检查是否抛出异常,需要有功能逻辑的断言。
### 编程语言要求
### API 设计规范
API根据其编程语言类型,需要遵守相应的OpenHarmony编程语言规范
关于这部分内容,请参见[《OpenHarmony API设计规范》](OpenHarmony-API-quality.md)
此差异已折叠。
......@@ -4,20 +4,35 @@
- ### Ability
应用的重要组成部分,是应用所具备能力的抽象。Ability是系统调度应用的最小单元,是能够完成一个独立功能的组件,一个应用可以包含一个或多个Ability。
应用的基本组成部分,是应用所具备能力的抽象。Ability是系统调度应用的最小单元,是能够完成一个独立功能的组件,一个应用可以包含一个或多个Ability。 在FA模型与Stage模型,分别定义了不同类型的Ability。
- ### AMS
Ability Manager Service,Ability管理服务。
- ### App Pack
上架应用市场的应用包的组织方式,包含一个或多个hap包,后缀名为.app。
- ### App Component
应用组件,每个Ability就是一个应用级组件。
- ### ArkCompiler
方舟编译器,是OpenHarmony内置的组件化、可配置的多语言编译和运行平台,包含编译器、工具链、运行时等关键部件,支持高级语言在多种芯片平台的编译与运行,并支撑OpenHarmony标准操作系统及其应用和服务运行在手机、个人电脑、平板、电视、汽车和智能穿戴等多种设备上的需求。
- ### ArkTS
OpenHarmony生态的应用开发语言。它在TypeScript(简称 TS)的基础上,扩展了声明式UI、状态管理等能力,让开发者可以以更简洁、更自然的方式开发应用。
- ### ArkUI
方舟开发框架,是一套极简、高性能、跨设备应用设计研发的UI开发框架,支撑开发者高效地构建跨设备应用UI界面。详情可参考[方舟开发框架开发指导](application-dev/ui/arkui-overview.md)
OpenHarmony上原生UI框架。是一套极简、高性能、跨设备应用设计研发的UI开发框架,支撑开发者高效地构建跨设备应用UI界面。详情可参考[方舟开发框架开发指导](application-dev/ui/arkui-overview.md)
- ### Atomic Service
原子化服务,OpenHarmony提供的一种全新应用形态。具有独立入口,用户可通过点击、碰一碰、扫一扫等方式直接触发,无需显示安装,由系统静默安装后即可使用,为用户提供便捷服务。
## B
......@@ -26,9 +41,22 @@
Bundle Manager Service,包管理服务。
## C
- ### C API
OpenHarmony SDK 提供的native开发接口。
- ### Continuation
流转,OpenHarmony系统提供的分布式操作,包括了跨端迁移和多端协同两种场景。
## D
- ### Derivative Framework
衍生框架,指桥接到原生框架上的三方框架。
- ### DevEco Device Tool
面向智能设备开发者,提供一站式的开发环境、一站式资源获取通道,实现了从芯片模板工程创建到开发资源挑选定制,再到编码、编译、调试、调优、烧录环节的全流程覆盖,帮助开发者实现智能硬件设备的高效开发。
......@@ -37,7 +65,6 @@
Distributed Management Service,分布式管理服务。
## F
- ### FA
......@@ -46,8 +73,7 @@
- ### FA模型
Ability开发框架支持的开发模型中的一种。API Version 8及更早版本的应用开发仅支持FA模型。FA模型将Ability分为[FA(Feature Ability)](#fa)和[PA(Particle Ability)](#pa)两种类型,其中FA支持Page Ability模板,PA支持Service ability、Data ability、以及Form ability模板。详情可参考[FA模型综述](application-dev/ability/fa-brief.md)。
Ability框架提供的一种开发模型。API version 8及更早版本的应用开发仅支持FA模型。FA模型将Ability分为[FA(Feature Ability)](#fa)和[PA(Particle Ability)](#pa)两种类型,其中FA支持Page Ability模板,PA支持Service ability、Data ability、以及Form ability模板。详情可参考[FA模型综述](application-dev/ability/fa-brief.md)。
## H
......@@ -55,6 +81,10 @@
OpenHarmony Ability Package,一个HAP文件包含应用的所有内容,由代码、资源、三方库及应用配置文件组成,其文件后缀名为.hap。
- ### HAR
OpenHarmony Archive文件。包含代码、资源和配置文件的中间格式。
- ### HCS
HDF Configuration Source是HDF驱动框架的配置描述语言,是为了实现配置代码与驱动代码解耦,以及便于配置的管理而设计的一种Key-Value为主体的文本格式。
......@@ -80,6 +110,12 @@
Intelligent Distributed Networking,是OpenHarmony特有的分布式组网能力单元。开发者可以通过IDN获取分布式网络内的设备列表和设备状态信息,以及注册分布式网络内设备的在网状态变化信息。
## N
- ### Native Framework
原生框架,指系统自带的开发框架。非原生的框架即三方框架。
## P
......@@ -87,18 +123,41 @@
Particle Ability,是在FA模型的Ability框架下无界面的Ability,主要为Feature Ability提供服务与支持,例如作为后台服务提供计算能力,或作为数据仓库提供数据访问能力。Particle Ability有三种模板,分别为Service模板(Service Ability)、Data模板(Data Ability)、以及Form模板(Form Ability)。
## S
- ### SA
System Ability的简称,这是由系统开发者编写的系统级组件。
- ### Secondary Framework
次生框架,指不依赖原生框架实现的三方开框架。
- ### Stage模型
Ability框架自API version 9提供的开发模型。Stage模型将Ability分为UIAbility和ExtensionAbility两大类,其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等等一系列ExtensionAbility。
- ### Super virtual device,超级虚拟终端
亦称超级终端,通过分布式技术将多个终端的能力进行整合,存放在一个虚拟的硬件资源池里,根据业务需要统一管理和调度终端能力,来对外提供服务。
- ### Stage模型
- ### SysCap
Ability开发框架支持的开发模型中的一种。从API Version 9起应用开发开始支持Stage模型。Stage模型将Ability分为Ability和ExtensionAbility两大类,其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等等一系列ExtensionAbility
全称是System Capability,指OpenHarmony中每个相对独立的特性,如蓝牙,WiFi,NFC,摄像头等,都是系统能力之一。每个系统能力对应多个API,每个API定义上包含了相应的SysCap标签
- ### System Type,系统类型
- MiniSystem,轻量系统:面向MCU(Microcontroller Unit,微控制单元)类处理器,例如ARM Cortex-M、RISC-V 32位的设备,资源极其有限,参考内存≥128KiB,提供丰富的近距连接能力以及丰富的外设总线访问能力。典型产品有智能家居领域的联接类模组、传感器设备等。
- Mini System,轻量系统:面向MCU(Microcontroller Unit,微控制单元)类处理器,例如ARM Cortex-M、RISC-V 32位的设备,资源极其有限,参考内存≥128KiB,提供丰富的近距连接能力以及丰富的外设总线访问能力。典型产品有智能家居领域的联接类模组、传感器设备等。
- Small System,小型系统:面向应用处理器,例如Arm Cortex-A的设备,参考内存≥1MiB,提供更高的安全能力,提供标准的图形框架,提供视频编解码的多媒体能力。典型产品有智能家居领域的IPCamera、电子猫眼、路由器以及智慧出行域的行车记录仪等。
- Standard System,标准系统:面向应用处理器,例如Arm Cortex-A的设备,参考内存≥128MiB,提供增强的交互能力,提供3D GPU以及硬件合成能力,提供更多控件以及动效更丰富的图形能力,提供完整的应用框架。典型产品有高端的冰箱显示屏等。
## U
- ### UI Component
UI组件,组成用户界面的一部分,可提供用户交互的能力。
## X
- ### XComponent
ArkUI提供的组件接口,满足开发者自渲染的需求。
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册