Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
XKZJ_WCL
Docs
提交
1bc2f50e
D
Docs
项目概览
XKZJ_WCL
/
Docs
与 Fork 源项目一致
Fork自
OpenHarmony / Docs
通知
1
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
D
Docs
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
1bc2f50e
编写于
4月 26, 2021
作者:
O
openharmony_ci
提交者:
Gitee
4月 26, 2021
浏览文件
操作
浏览文件
下载
差异文件
!294 api治理章程更新
Merge pull request !294 from zhangyongzhi/master
上级
47cb8d2c
273562c7
变更
1
隐藏空白更改
内联
并排
Showing
1 changed file
with
33 addition
and
29 deletion
+33
-29
zh-cn/design/OpenHarmony-API-governance.md
zh-cn/design/OpenHarmony-API-governance.md
+33
-29
未找到文件。
zh-cn/design/OpenHarmony-API-governance.md
浏览文件 @
1bc2f50e
...
...
@@ -14,19 +14,20 @@
![](
figures/API-Scope-And-Definition.png
)
OpenHarmony API按使用方分类包括:
-
PublicApi:公开发布,提供给三方应用开发
使用的API。
-
SystemApi:非公开发布,仅授权系统应用
可使用的API。
-
TestApi:受限发布,仅适用于xTS或应用调试阶段可使用的API
。
OpenHarmony API按
可授权
使用方分类包括:
-
Public API:公开发布,提供给三方应用开发使用的API。
-
System API:非公开发布,仅授权系统应用(被额外授予某些特定系统权限能力)可
使用的API。
-
Test API:受限发布,仅适用于xTS或应用调试阶段
可使用的API。
如无特别说明,本章程定义的条款同时适用于Public API、System API或Test API等三种OpenHarmony API。针对System API和Test API的额外要求或例外说明,通过特别说明方式加以补充说明
。
OpenHarmony API按编程语言分类包括:
-
Java API:面向应用开放的Java编程语言接口。
-
JS API:面向应用开放的JavaScript编程语言接口。
-
Native API:面向应用开放的C/C++编程语言接口。
如无特别说明,本章程定义的条款同时适用于Java API、JS API和Native API等三种编程语言OpenHarmony API。
## API治理
### 角色与职责
|
**涉及角色**
|
**API治理中的职责**
|
...
...
@@ -43,7 +44,6 @@ API评审流程如下:
![](
figures/API-Review-Process.png
)
主要过程说明:
1.
API评审申请、代码提交(Owner:Contributor),除代码提交外,如果涉及API新增或变更需同步提交相应的API设计文档,详细说明API的需求来源、场景与使用方法、权限设计、隐私保护澄清等,详见后面的API评审申请要素。为避免后续的返工,Contributor可以在正式的API评审申请、代码提交之前,先通过邮件方式将API设计文档提交Committer、领域SIG、API SIG等相关人员预审。
1.
代码评审(Owner:Committer),代码评审和API预审,涉及API提交CodeReview通过后,还需要进一步领域SIG评审。如果单次提交同时涉及多个领域的API新增或变更,相应的API评审申请和代码需要同时提交给相关领域的Committer评审,只有所有对应领域的Committer都完成CodeReview后才能进入下一评审环节。
1.
API评审(Owner:领域SIG),新增API相关的代码提交评审,领域SIG评审通过即可代码合入;变更API相关的代码提交,领域SIG评审通过后,还需要进一步提交API SIG。如果单次提交同时涉及多个领域的API新增,相应的API评审申请和代码需要同时提交给相关领域的SIG评审,只需一个领域SIG评审通过即可代码合入。如果单次提交同时涉及多个领域的API变更,相应的API评审申请和代码需要同时提交给相关领域的SIG评审,只有所有对应领域的SIG都要评审通过才能进入下一评审环节。
...
...
@@ -51,17 +51,22 @@ API评审流程如下:
1.
评审完成。
### API评审申请要素
如果涉及API新增或变更需同步提交相应的API设计文档
,建议包含如下要素:
如果涉及API新增或变更需同步提交相应的API设计文档
。
针对新增API,需要包含如下要素:
1.
需求来源与使用场景(必须)。
1.
API现状与差距分析,说明API新增或变更的必要性(必须)。
1.
API原型设计与使用方法说明(必须);必要时,可以进一步包含相应的使用样例(可选)。
1.
API权限设计(必须)。
1.
API隐私保护方案与要求满足情况澄清(必须);
1.
提交代码的同时提交相应的API参考(必须);必要时,可同步提交相应的开发者指南文档(可选)。
1.
针对老接口的处理方式(废弃、隐藏或彻底删除)、替代接口和相应的应用兼容措施(可选,如果涉及API变更,则必须包含)。
1.
兼容性/性能/功耗/可靠性/测试等相关情况说明(可选,如不满足本章程 “4 API设计要求”,则必须包含相关说明)。
针对变更API,需要额外包含如下要素:
1.
针对老接口的处理方式(废弃、隐藏或彻底删除)以及对使用老SDK开发应用的兼容措施(必须);
2.
变更影响、替代接口和相应的应用适配方案(必须)。
3.
刷新ChangeLog(必须) 和 API-diff文档(涉及JS/Native API变更,必须;Java API的差异报告可工具化生成,不需要人工提交)。
## API设计要求
### 一致性要求
1.
概念一致性:基于场景的业务模型抽象,形成OpenHarmony的连贯、一致、自恰的用户程序模型和业务概念。
...
...
@@ -73,7 +78,6 @@ API评审流程如下:
### 易用性要求
以“能力使用者”视角,而不是“能力提供者”视角设计API:
1.
可理解:API命名和功能特性必须容易理解。
1.
易使用:提供简单易用的API,减少API之间不必要的耦合,避免多个无之间关联关系API之间调用顺序的依赖,尽可能使调用者优雅,尽量避免使用单一功能时必须同时组合调用多个包/模块或类中的多方法才能实现。
1.
避免误导:提供使用者期望的能力,避免误导,减少误用。
...
...
@@ -87,14 +91,11 @@ API评审流程如下:
1.
不用或少用缩写,业界通用术语遵从行业习惯允许使用缩写。
1.
包名/模块名/命名空间前缀约定:
1.
Java API 统一包名: package ohos.
\*
。
2.
JS API 统一模块名:@
system
.
\*
。
2.
JS API 统一模块名:@
ohos
.
\*
。
3.
Native API 统一命名空间:namespace OHOS.
\*
。
4.
引用外部开源代码的,可以保留原包名/模块名/命名空间,也可以按照上述规则统一进行替换。
7.
包名/模块名/命名空间最短不少于2段,最长不超过4段;每一段建议使用一个单词,最长不超过2个单词。
8.
类名、方法名/函数名、成员变量、变量名最多不超过4个单词。
4.
引用外部开源代码的,可以保留原包名/模块名/命名空间,也可以按照上述规则对包名统一进行替换。
1.
包名/模块名/命名空间最短不少于2段,最长不超过4段;每一段建议使用一个单词,最长不超过2个单词。
1.
类名、方法名/函数名、成员变量、变量名最多不超过4个单词。
### 权限控制要求
1.
完备性原则:一切穿透应用沙箱的行为都需考虑使用权限来管控。
...
...
@@ -119,34 +120,37 @@ API评审流程如下:
1.
如果执行过程中可能抛出异常,则API参数必须包含相关的异常描述。
1.
必须包含API的起始版本号(使用@since注释标记)。
1.
可选包括本模块或类自己的版本号(使用@version注释标记)。
1.
涉及API变更(不兼容),必须同步交付API-Diff和ChangeLog文档。
### 兼容性要求
1.
按严格程度从高到低,API兼容要求包括:契约兼容 > 二进制兼容 > 源码兼容。
1.
源码兼容:指版本演进后,开发者已有的源代码可正常编译通过。
1.
二进制兼容:指版本演进后,开发者已有程序不用重新编译可正常链接、运行。
1.
契约兼容:也称语义兼容,指版本演进后,开发者原有程序行为不发生变化。
1.
OpenHarmony API后向兼容必须满足二进制兼容要求,常见破坏二进制兼容的API变更包括:
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.
OpenHarmony API在特定目的下,如Bugfix,允许不遵守契约兼容要求。
1.
禁止“原型相同、功能不兼容”的API修改,可受限使用“废弃old-api、新增new-api”的方式进行修改。
1.
根据发布类型不同,API的生命周期和兼容性要求:
![](
figures/API-Lifecycle.png
)
1.
Canary版本:相同API Version的多个Canary版本之间要求保持API兼容,Canary阶段新增的API允许在后续的Canary版本中标记为废弃或隐藏。Canary阶段新增的API允许在后续第一个Beta版本中彻底删除。
2.
Beta版本:相同API Version的多个Beta版本之间要求保持API兼容,Beta阶段新增的API允许在后续的Beta版本中标记为废弃或隐藏,API Stable版本发布之后API即冻结,之后再发布的Beta版不允许任何形式的API新增或变更。Beta阶段新增的且在API Stable版本中标记为废弃或隐藏的API允许在后续第一个Release版本中彻底删除。
3.
Release版本:通过Release版本对外发布的API,需要遵守对外部开发者的“契约承诺”,原则上不允许对已经Release发布的API进行不兼容修改,受限允许对已发布的API进行废弃。已经Release发布的API废弃基本要求包括:
1.
废弃接口标记。
2.
提供可替代接口。
3.
废弃API至少保留5个API Version版本(对废弃5个API Version的API可以彻底删除,不再支持)。
1.
Canary版本:早期发布的预览版本,不承诺API稳定。
1.
对上一Release发布版本保持API兼容。
1.
相同API Version的多个Canary版本之间无API兼容性要求。
1.
Beta版本:公开发布的Beta测试版本,不承诺API稳定。
1.
对上一Release发布版本保持API兼容。
1.
对同一API Version的早期发布的Canary版本不兼容。
1.
相同API Version的多个Beta版本之间无API兼容性要求。
1.
API Stable版本发布之后API即冻结,之后再发布的Beta版不允许任何形式的API新增或变更。
1.
Release版本:正式发布版本。
通过Release版本对外发布的API,需要遵守对外部开发者的“契约承诺”,原则上不允许对已经Release发布的API进行不兼容修改,受限允许对已发布的API进行废弃。已经Release发布的API废弃基本要求包括:
1.
废弃接口标记。
1.
提供可替代接口。
1.
废弃API至少保留5个API Version版本(对废弃5个API Version的API可以彻底删除,不再支持)。
### 性能/功耗/可靠性要求
1.
应及时响应,避免调用者等待;如果API调用执行时间过长应设计为异步方式。
...
...
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录