做网站可以用什么数据库自己做网站出证书

当前位置： 首页 > news >正文

做网站可以用什么数据库,自己做网站出证书,深圳注册公司流程和费用,pageadmin的最新版本OpenHarmony API 设计规范 修订记录 版本作者时间更新内容v0.1#xff0c;试运行版OpenHarmony API SIG2022年11月初版发布 目的 API是软件实现者提供给使用者在编程界面上的定义#xff0c;API在很大程度上体现了软件实体的能力范围。 同时#xff0c;API定义的好坏极…OpenHarmony API 设计规范 修订记录 版本作者时间更新内容v0.1试运行版OpenHarmony API SIG2022年11月初版发布 目的 API是软件实现者提供给使用者在编程界面上的定义API在很大程度上体现了软件实体的能力范围。 同时API定义的好坏极大影响了使用者的体验。 为了保障OpenHarmony生态健康发展保证开发者使用体验现制定OpenHarmony API设计规范。 范围 OpenHarmony API主要包含了对应用开放的外部API以及系统实现部分的内部API。 本设计规范主要用以约束以下API不区分编程语言 OpenHarmony Public APIOpenHarmony System API 关于OpenHarmony API的分类请参见《OpenHarmony API治理章程》。 接口设计目标 好的接口设计应该满足以下四点 可使用 Operational这一点是毋庸置疑的接口必须要能完成它提供的能力。可使用是最基本的要求。富于表现力 Expressive与可使用同样重要的是借助接口使用者能够清晰表达他们想要做的事情。简单 Simple接口的设计要保证学习和使用简单避免难于理解或者使用出错的情况发生。可预测 PredictableAPI应当始终一致的按照接口的定义完成使命。如果接口定义中不包含出错和异常的情况那么这个API被调用任意多遍都不应该发生任何异常。当然如果实际情况是有可能出错或者失败的那就要在接口定义中说明清楚什么情况下会出什么错并准确的在相应的时机下返回对应的错误。 除此之外API的设计还应该注意以下几点 API的稳定性和一致性是最重要的API并非越多越好。API命名应当容易理解API命名并非越短越好。API应当做好封装和抽象并非暴露的信息或者能力越多越好。 从开发者使用API的阶段上来看API应当做到 在学习阶段 容易理解容易上手在开发阶段 富于表现力简单可预测在维护阶段 行为稳定容易维护 API设计概述 为了使得规则尽可能通用本规范不会涉及具体编程语言的差异也不会涉及编码规约。这部分内容只要遵守相应的本地要求即可。 从整体上来看本规范将API规范分成发布前评审规范和发布后评价两个部分。 发布前评审规范 是对于API的最基本要求所有API必须满足这些要求才能通过评审。发布后评价 尽管在发布前已经做了很多的规则要求。但是仍然不能保证API是完美的。因此API发布后仍然要保持对API的关注。发布后的审视将影响对API提供者的评价。 以下是所有的API设计规则的罗列以供快速索引详细的说明在后文中展开。 每一个OpenHarmony API提供者都应该熟悉以下规则。 发布前评审规范 易用性 规则1符合编码规则规则2准确使用英语语法规则3合理使用缩写规则4准确使用对仗词规则5准确使用设计/架构模式规则6避免有争议的命名规则7参数类型合理规则8参数数量合理规则9参数顺序合理规则10返回值定义完备规则11异常定义合理规则12从正面表达规则13降低出错的可能性规则14避免顺序耦合规则15准确表达所有逻辑规则16注意封装规则17单一职责可用性 规则18保证可靠性规则19功能完备规则20考虑权限与隐私保护规则21考虑并发环境规则22注意资源管理闭合规则23考虑重试逻辑规则24满足幂等要求规则25考虑设备通用性一致性 规则26保证术语、概念一致性规则27保证设备间行为一致性规则28注意版本演进一致性规则29命名风格保持一致规则30参数顺序保持一致规则31同步/异步风格一致兼容性 规则32注意新旧系统版本的兼容性规则33二进制向后兼容性API资料 规则34模块、命名空间、类需要包含基础说明规则35使用场景说明清晰规则36接口说明准确规则37参数说明准确规则38返回值/异常描述准确规则39元信息完备规则40风格一致组织方式 规则41分层合理规则42模块划分合理规则43应用描述文件也是接口的一部分质量属性 规则44性能满足要求规则45功耗设计合理规则46需要保证可测试性规则47考虑环境适应性 发布后评价 稳定性 规则48接口废弃率/变更率越低越好安全性 规则49避免接口被滥用规则50避免接口被利用可维护性 规则51能承载业务演进规则52功能扩展后不影响原先行为规则53文档和资料配套更新不可替代性 规则54保证API之间正交开发者反馈 规则55关注开发者反馈 发布前评审规范说明 易用性 任何设计都应该考虑易用性。对于OpenHarmony API来说易用性需要考虑以下几个方面 命名 规则1符合编码规约 API的定义首先应当满足所属项目的编码规约例如大小写的定义、下划线、连字符规则、前缀规则等。 对于OpenHarmony生态而言可参考如下编码规约 《OpenHarmony JavaScript语言通用编程规范》《OpenHarmony C语言编程规范》《OpenHarmony C语言编程规范》《OpenHarmony CC 安全编程指南》《OpenHarmony HDF驱动编程规范》规则2准确使用英语语法 API命名只允许使用英语。通常类的名称是名词例如XXXManagerXXXServiceXXXAnimation等。函数通常是动词或动宾结构例如start()createUser()startBoot()等。 对于一个名称叫做Start的类或者一个叫做ball()的函数通常是错误的做法。 另外还请注意及物动词和不及物动词避免语法错误。对于动词根据场景需要注意时态。例如如果时机上就存在“开始传输”和“渲染完成”这些事件就应该用上transferStarted()以及renderDone()这类的表达。 规则3合理使用缩写 应当尽可能避免使用缩写。缩写不仅仅是难于理解还有一个问题是一个缩写可能会有多个解释在上下文信息不全的情况下使用者会很难分辨。 如果是大家都熟知的缩写是允许的除此之外应该尽量避免。尤其是只有自己能明白的缩写这是禁止的。 规则4准确使用对仗词 在语言表达中同一个含义可能有很多个类似的词可以表达例如 词语近义词senddeliver, dispatch, announce, distribute, routefindsearch, extract, locate, recoverstartlaunch, create, begin, openmakecreate, set up, build, generate, compose, add, new 但在API命名中应当注意对仗词的使用。 例如如果你使用了add就应该使用remove而不是destroy。使用了increase就应该使用decrease而不是reduce。 下面是一些常见的对仗词 词语对仗addremoveincreasedecreaseopenclosebeginendinsertdeleteshowhidecreatedestroylockunlocksourcetargetfirstlastminmaxstartstopgetsetnextpreviousupdownnewold 规则5准确使用模式 设计模式或者架构模式其实是软件行业的“行话”。既然是行话就要正确的使用否则别人就可能误解你的意思。 因此当你的接口中包含了StrategyBuilderFactorySingleton这类的词语时请确保你准确理解了这些设计模式并且正确使用了它们。 另外如果你确定的是在使用某个模式那就准确的在名称上使用标准术语不要随便修改词性或者打乱名称的词语顺序这样使用者会更容易理解。 规则6避免有争议命名 命名要遵守的底线是应该避免有争议的名称。这其中包括但不限于任何违反法律、产生宗教争议、或导致种族歧视的词语。 当然使用脏话也是绝对禁止的。考虑到OpenHarmony会使能千行百业对于避免有争议命名需要思考得更多。 参数 规则7参数类型合理 通常使用类类型参数比使用简单类型要更好。 例如对于下面的一组接口看似没什么问题 addPerson(string id, string name, int age)removePerson(string id, string name, int age)modifyPerson(string id, string name, int age) 但是这个定义不便于扩展因为后期可能要新增参数。但是如果一开始就通过一个类类型Person来定义参数则添加一个字段就很容易并且对于接口本身不用做任何改变。 使用类类型而不是简单类型还有一个好处是参数数量会少更容易记忆。 规则8参数数量合理 参数数量应当控制在7个以内。在更多的情况下参数控制在3~5会更容易使用。 在任何情况参数的数量都不应当超过10个这种接口通常很难记忆和使用。如果遇到这种情况通常是对类型没有做很好的封装或者是接口的实现逻辑包含太多的内容。请考虑拆解。 规则9参数顺序合理 在一些编程语言中常常会以先输入参数、后输出参数的顺序来组织参数列表。 但其实如果能再根据参数的大小逻辑关系、参数的重要性来进行排序那对于使用者来说会更容易记忆和使用。 比如可选参数应该放到必选参数的后面回调函数作为参数应该放到最后等。以fs.readFile 方法为例路径参数是必填的encoding 和 flag 是有默认值的。 fs.readFile(path[, options], callback)fs.readFile(/etc/passwd, (err, data) {if (err) throw err;console.log(data); });fs.readFile(/etc/passwd, {encoding: utf-8,flag: r }, (err, data) {if (err) throw err;console.log(data); });返回值 规则10返回值定义完备 返回值定义完备需要做到不能只考虑正常情况对于接口的定义也要考虑异常和无效的情况。要让开发者能合理处理。 例如 对于数字类型的返回值要定义清楚返回的范围什么情况下会出现极值。对于布尔类型的返回值要定义清楚什么时候返回true什么时候返回false。对于数组或者集合类型的返回值要定义清楚什么时候返回null什么时候返回包含空元素的集合。对于枚举类型的返回值要确保每种情况都准确定义了。规则11异常定义合理 异常是特殊情况的返回这通常意味着输入参数无效或者函数根本无法正常处理。 对于同一个模块或者同样的业务在何种情况下返回错误值在何种情况下直接返回异常应该有统一的定义。 另外针对同样的异常情况下应当返回同样的异常类型。 保持一致可以很大程度上降低开发者的使用难度并且避免使用出错。 其他 对于易用性而言除了上面提到的内容还有一些推荐的做法可以降低开发者的使用难度。 规则12从正面表达 从正面表达可以降低开发者的思考成本。 通俗来说就是接口的命名尽量使用肯定的词语而不是否定方式的表达。因为否定表达很难理解。 下面是一个反例 if (!isNotAccessible() || !isNotWritable() || !isNotPrintable())如何接口都是正面表达就更容易理解了下面是推荐的做法 if (isAccessible() isWritable() isPrintable())规则13降低出错的可能性 调用者使用错误很大程度在于参数传递上。 例如下面这个函数。第二个和第三个参数都是布尔值这样使用者很容易记错顺序或者搞不清楚该传入true还是false。 declare function findString(text: string, isForward: boolean, isCaseSensitive: boolean): string;通过枚举在定义上就避免这种错误存在的可能 enum SearchDirection {FORWARD,BACKWARD }; enum CaseSensitivity {SENSITIVE,INSENSITIVE }; declare function findString(text: string, direction: SearchDirection, sensitivity: CaseSensitivity): string;很多时候通过枚举代替布尔值以及整数表达的类型可以减少使用者出错的可能性。 再者通过将多个参数组成一个类型的形式也可以降低参数传递出错的可能性。 规则14避免顺序耦合 软件设计要尽可能保证高内聚低耦合。这一点对于大型项目尤其重要。 耦合表达了软件模块之间的依赖程度耦合过深常常意味着架构设计没有做好。 从一个软件静态结构或者分层架构图上可以看得出如果模块之间的依赖关系比较少上下层之间有明显的调用方向则是比较好的设计。相反的如果模块之间依赖关系非常复杂或者上下层之间存在相反方向的调用链则不是一个好的结构。 耦合有很多种对于接口来说顺序耦合就是要注意的。顺序耦合是指类中方法需要按照某个特定的顺序调用才能工作。 类似下面这组命名的接口很可能就是顺序耦合 doSomethingFirst() doSomethingSecond() doSomethingThird()这种设计的问题在于对于使用者的要求太高了很容易用错。 对于这类问题通常可以使用模板方法设计模式来解决。 规则15准确表达所有逻辑 有些接口是用来查询信息的例如getUserAccount()。有些是进行操作的会修改数据例如createUserAccount()。 永远不要在一个看起来是查询操作的接口里面去做修改数据的动作 因为这样使用者会非常的迷惑。 更通用的来讲 接口的名称应当表达它所做的所有事情 不要有所隐瞒。只有这样在阅读代码的时候才能更容易理解代码到底做了什么。 如果接口包含了内容太多很难通过几个单词描述清楚所做的所有事情该怎么办对于这种情况通常意味着需要将这个接口拆分成多个因为这个接口不够“内聚”。 还有一些情况下大家在做某件事的时候会本能的以为别人也有同样的背景认识。但事实往往并不是这样。在编程时也是一样。 例如对于一个描述编程语言的字段可能会将其命名为language。这是因为大家默认认为已经在讨论编程语言了但是language到底是编程语言还是国际化语言是不是叫做programmingLanguage更好一些呢 当然对于这一条还是要举一个反例不要走到另外一个极端如果类名或者namespace名称中已经明确带了一个前缀在函数中就没必要再重复一遍了。毫无信息量的冗余是没有必要的。 规则16注意封装不暴露实现细节 对于面向对象编程来说大家都知道“封装”的重要性。 这意味着系统能力应当尽可能封装好实现细节提供简洁的接口供调用者使用。 这就好像冰山埋在水里的部分不管多庞大露在水面上的部分要足够的小足够的简洁。这才是友好的界面Interface。 封装的重要性不仅仅是让开发者容易使用。其实也是使得开发者不容易出错。举一个生活中的例子电子工程师将房间的电路线接好之后只留一个开关按钮给到用户这就是一个很好的封装。既避免了让用户理解复杂的电路结构方便使用也不会产生触电出错的风险。 规则17单一职责 一个 API 应当尽量只做一件事情尽可能保持单一核心的职责。例如 // 不推荐 view.fetchDataAndRender(url, templete);// 推荐 let data view.dataManager.fetchData(url); view.render(data, templete);这么做的目的是因为开发者可以根据需要按最小单位来使用接口。也可以根据多个单一职责的组合来进一步封装自己需要的业务逻辑。 单一职责与注重封装性在一些情况下可能是矛盾的如果提供了多个单一能力的接口势必需要使用者关心多次的调用细节。 在这种情况下需要从封装的“层次”来考虑决定接口提供给开发者的到底是哪个层级的能力面向高层次使用者的一件事对于低一个层次来说可能就是多件事情。 可用性 规则18保证可靠性 操作系统所提供的接口必须是完全可靠的。 当然可靠性不意味每次调用都是成功的。例如在资源已经耗尽的情况下应当给调用者合理的返回值或者异常。 每个接口必须针对所有的情况进行准确的定义并在相应的情况下按照定义的行为完成工作。 没有按照预定行为返回结果或者无故导致应用程序异常都属于不可靠行为。 规则19功能完备 每个特性或者能力在规划时需考虑到功能的完备性。不应当出现在支持的范围内某个流程中断或者某个选项缺失的情况发生。API设计者应当做好足够的验证和推演。 即便操作系统的特性常常会伴随系统版本几年内才能完全迭代完备。但是对于每一个特定版本在其包含的范围内应当是闭合的自洽的。这要求模块的设计者划分好版本迭代的边界。 规则20注意权限和隐私保护 任何涉及到用户数据、用户隐私的接口都必须做好权限限制和数据保护。 对于权限控制应当遵循以下几个原则 完备性原则一切穿透应用沙箱的行为都需考虑使用权限来管控。最优粒度原则一个权限只保护一类对象一个接口只需申请最小粒度的权限。清晰完整原则权限定义中必须清晰说明保护对象、开放范围、敏感级别。最小开放原则一个权限仅对确有正当业务需求的应用开放开放控制可通过权限来实现。 对于隐私包含应当遵守以下几个原则 API调用的返回仅包含必要的内容 避免携带额外信息。API调用不允许获取、收集用户个人数据 除非通过用户权限管控、由用户授权同意。API涉及跨应用调用时如涉及个人数据向被调用者的披露由调用方在隐私声明中说明披露的数据类型、数据接收者和数据使用目的。API涉及到用户敏感数据如电话、通讯录、媒体等访问时需要使用system picker的机制禁止API通过申请敏感权限方式访问。API开放禁止捆绑与所开放能力不相关的功能。 规则21考虑并发环境 保证所有的接口线程安全需要付出很大的代价程序复杂度、性能影响因此OpenHarmony API不必要求所有接口线程安全。只需根据需要选择即可。 但是对于设计上就是为了并发环境使用的接口必须做好相应的设计和说明。 当然对于接口的内部实现中应当尽可能避免出现线程不安全的问题发生。 规则22注意资源管理闭合 在一些情况下有些接口包含了动态资源的申请。此种情况下这些接口也需要考虑到资源的释放。 如果申请的资源是直接返回开发者的则需要提供相应的接口来释放资源。 如果资源没有直接返回给开发者则接口自身要考虑到资源的生命周期以及释放的时机。 对于有资源使用上限的情况应当给开发者说明清楚。并且提供接口查询是否已经到达上限。 对于独占资源更加应当注意资源的释放时机。 规则23考虑重试逻辑 对于可能失败的接口应当考虑好给开发者相应的机制来重试。例如对于相机这类独占的资源一旦有某个进程使用了其他进程就无法获取到。这种情况下应当提供接口给开发者查询是否可用的接口。 在一些情况下为了避免开发者反复尝试还需要提供给开发者状态监听的机制。 并且API要明确客户端调用失败后能够发起重试的最大次数。 规则24满足幂等要求 在数学中幂等用函数表达式就是f(x) f(f(x))。例如求绝对值的函数就是幂等的abs(x) abs(abs(x))。 计算机科学中幂等表示一次和多次请求某一个资源应该具有同样的效果或者说多次请求所产生的影响与一次请求执行的影响效果相同。 具体到实际场景文件打开或者的硬件资源使用打开一次和打开多次其效果应当是一样的不应该有其他副作用。当然关闭也是类似。 规则25考虑设备通用性 OpenHarmony是为多种不同类型设备设计的统一操作系统。 考虑到设备的复杂性接口的设计应当要能面对多种设备的适用性。例如 对于用户界面的控件要考虑到不同屏幕尺寸的大小。对于数据的存储要考虑到不同大小的存储空间。对于用户输入事件要考虑不同的用户交互方式触摸、语音、按键等。 当然有一些API只在某些特定设备上才有例如 健康类传感器只在穿戴设备上有车控类接口只在车机设备上有 这种情况请参考《SysCap使用指南》来标定API的适用范围。 一致性 规则26保证术语、概念的一致性 为了容易理解接口在命名和说明上应当注意术语和概念的一致性不应该出现“方言”。基于场景的业务模型抽象形成OpenHarmony的连贯、一致、自恰的业务概念。 在这方面应当遵循以下原则 每个概念只应该有 唯一 的一个术语同一个对象不应该有两个名称。术语命名应该是 贴切的 可解释 易理解 。术语的定义应当 精准、无二义。对于业界通用术语 不应该重新定义 应当遵循业内做法。 总体来说要避免随意添加术语概念尽可能以《OpenHarmony 技术术语集》为准。如果需要可以在术语集中新增词条。 规则27保证设备间行为一致性 在默认情况下同一个接口在不同的设备上应当保证行为是一致的。 对于因为设备形态而导致的行为不一致应当给予开发者充分的说明并且提供相应的检查机制。 规则28注意版本演进一致性 在默认情况下所有接口应当保证在系统版本演进的情况下其行为是一致的。如果在新版本上出现了行为不兼容的变更最低要求是需要对应用的目标版本做区分处理。 简单而言接口的行为变更不能影响已经开发完的应用。 规则29命名风格保持一致 在一些 API 设计的场景中即使命名已经做到准确但在有些情况下仍然可能碰到不一致的场景。比如API 中经常会看到 picture 和 image、path 和 url 混用的情况这两组词的意思非常接近容易出现混乱。在指代同一内容时应该使用相同的命名。 例如下面这些接口都是为了获取媒体资源但是命名风格不一致。 declare function getMediaAsserts(): ArrayMediaAssert; declare function getAudios(): ArrayAudioAssert; declare function getVideos(): ArrayVideoAssert; declare function getImages(): ArrayImageAssert;应该修改为 function getMediaAsserts(): ArrayMediaAssert; function getAudioAsserts(): ArrayAudioAssert; function getVideoAsserts(): ArrayVideoAssert; function getImageAsserts(): ArrayImageAssert;规则30参数顺序保持一致 为了开发者便于理解对于同一个命名空间或者是同一个模块来说其成套的接口的参数顺序应当是一致的。 例如deviceId和missionId在单个接口中的顺序没有强制要求但是在同一模块接口中必须保持顺序一致。 function getMissionInfo(deviceId: string, missionId: number): PromiseMissionInfo; function getMissionSnapShot(deviceId: string, missionId: number): PromiseMissionSnapshot;// 正确 function getLowResolutionMissionSnapShot(deviceId: string, missionId: number): PromiseMissionSnapshot;// 错误 function getLowResolutionMissionSnapShot(missionId: number, deviceId: string): PromiseMissionSnapshot;规则31同步/异步风格一致 异步接口应该可以通过入参和返回值判断出来风格上要保持统一。例如 // Callback形式 function getDefaultDisplay(callback: AsyncCallbackDisplay): void; // Promise形式 function getDefaultDisplay(): PromiseDisplay;如果同时提供了同步和异步接口可以在同步函数名后加上后缀Sync加以区别例如 function getDefaultDisplaySync(): Display;如果只提供了同步接口且返回值不是void可以不用加后缀例如 function registerMissionListener(listener: MissionListener): number;兼容性 规则32注意新旧系统版本的兼容性 API 变更的成本非常高在设计之初就应该做尽可能完备的考虑。但是API变更始终是系统发展过程中不可避免的。 API 变更要保证向后兼容原则API 变更后废弃的 API 要在源码和文档中显著标识 deprecated并引导开发者使用变更后 API 。 废弃的 API 要保证其功能仍然可用至少保留5个版本。5个版本后在充分告知开发者并给与充分的时间供开发者修改后可予以删除。 规则33二进制向后兼容性 二进制兼容指版本演进后开发者已有程序不用重新编译可正常链接、运行。这也意味着二进制兼容是保证在版本升级的情况下对象实例的内存布局不会发生变化。 以C接口为例常见破坏二进制兼容的API变更包括 任何API元素删除添加新的虚函数改变类的继承改变虚函数声明时的顺序添加新的非静态成员变量改变非静态成员变量的声明顺序 由于C接口相比C接口在二进制兼容性上有天然的优势所以OpenHarmony的Native API推荐使用C接口定义。 API资料 API的很多信息需要通过文档和资料进行说明因此配套的这些内容也应当做好质量管理。 规则34模块、命名空间、类、函数需要包含基础说明 每个模块、命名空间、类和函数都需要包含基本的说明。 对于关键模块、复杂模块需要有详细的说明。 说明采用英文的形式。 规则35使用场景说明清晰 所有接口应当提供示例代码覆盖常见使用场景。 复杂接口需要详细说明使用场景。可以在接口的说明上增加详细教程的链接。 规则36接口说明准确 接口说明的文字不应该出现拼写错误或者错别字。 所有代码示例应当保证能够正常运行。如果接口在不同版本上存在行为不一致则需要针对每种情况做详细说明。 对于废弃接口需做明确标记并做好替代接口说明。 规则37参数说明准确 对于API的每一个参数都应该说明清楚。例如 如果是非简单类型则需说明清楚是否允许参数为空如果是枚举类型则需针对每个枚举值说明清楚使用场景如果是可选参数则需说明清楚什么时候该传参什么时候可省略 规则38返回值/异常定义准确 如果接口有返回值/异常需要在接口说明中描述完整。例如 /*** Sync function of rename.* param {string} path - path.* returns {void} rmdir success.* throws {BusinessError} 401 - if type of path is not string.* throws {BusinessError} 201 - if permission denied.* syscap SystemCapability.FileManagement.File.FileIO* since 7*/ declare function rmdirSync(path: string): void;规则39元信息完备 接口的方法说明上应当包含基本的元信息例如syscap、since等。 元信息描述了API自身的基本信息。工具和SDK会利用这个信息进行相应的处理例如针对已经废弃的接口会给出警告提示。 规则40风格一致 API的说明资料在风格和样式上应当保持一致。例如文字的加粗资料图片的配色等。 组织方式 规则41分层合理 操作系统通常是以分层的模型来进行架构的。这意味着每一层要解决不同层次上的问题。 因此接口的设计也要注意相应的层次。 可以使用建筑行业来进行类比所有的建筑都会包含墙体和房间的门。墙体是有砖块构成的门是有木料构成的。在这种情况下抽象可能会分为下面几层 第一层是基本都原材料包括水泥、沙子、木材等第二层是用原材料构建出来的建筑元素例如门、窗户、墙体等第三层是房间的种类例如卧室、卫生间、客厅等最后最上面一层是各种不同用途的建筑。例如酒店、公寓等 这里每一层所要考虑的概念和要处理的问题都是不一样的请仔细思考你提供的API是在哪一个层次上。 规则42模块划分合理 大家不仅要关注水平层面的分层也应该关注垂直层面的划分。因此模块的组织也同样重要。OpenHarmony的接口是以命名空间的形式组织的。一个命名空间通常对应了一个模块。 从子系统的角度一个较小的子系统应该尽可能将接口放在同一个命名空间中。较大的子系统可以提供多个命名空间。 规则43应用描述文件也是接口的一部分 接口的英文是Interface这个词还有界面的意思。操作系统提供给开发者的接口并不仅仅是编程接口。任何公开给开发者的机制都是API的一部分。 这其中最明显的就是应用描述文件这些文件也需要按照接口规范一样的规则来管理。 质量属性 规则44性能满足要求 操作系统所提供的接口所有上层应用都可能会使用到因此其实现的性能应当是能够满足实际要求的。 下面是一些举例 应及时响应避免调用者等待如果API调用执行时间过长应设计为异步方式。接口存在大量数据传输时应考虑使用共享内存、消息队列等。尽可能减少新增进程实体。对使用资源的API调用需要能及时释放资源异常场景具备容错机制保障资源及时释放。 规则45功耗设计合理 OpenHarmony 操作系统在设计之初就需要面向多种不同类型的设备这些设备中绝大多数是无源设备。因此功耗的考虑是毋庸置疑的。 每个功能/机制在实现上应当把功耗的合理性作为最基本的要求。除此之外对于高功耗的接口应当在说明中给开发者充足的解释并且对于使用方式给与足够的指导。 同时在使用上要避免开发者错误的使用。例如在设备锁屏之后或者应用切换到后台之后就应当停止高功耗的行为。 另外还应当注意在版本演进过程中功耗不出现劣化。 规则46需要保证可测试性 完备的自动化测试用例可以带来很多好处 开发过程中提前快速发现问题提高接口质量。版本迭代时保证代码修改不影响功能提高代码修改的信心。确保接口向后兼容性。 所以对于一个OpenHarmony API都要求做到以下几点 新增API必须同步交付API自动化测试用例用例100%覆盖API接口。用例场景单一单条用例覆盖接口单个功能场景简化单条用例代码逻辑。用例执行高效每条用例执行时间控制在毫秒级。用例执行全自动化接口用例需要达成100%自动化。用例有效性用户要求必须存在断言且不能仅是检查是否抛出异常需要有功能逻辑的断言。 规则47考虑环境适应性 考虑到用户的个性化操作系统通常会提供一些环境自定义的能力例如语言国际化、浅色/深色主题、字体大小等。 对于这方面相关的接口在开发者没有传递指定参数的情况下应当能够根据当前所属的环境自适应的返回相应环境下的结果。 发布后评价说明 尽管在API发布前已经做了多方面规则约束但总可能还有一些问题在开发者使用之后才能发现。 即便是这样但并不意味着在设计API之初不需要考虑这些问题。 相反的大家应当时刻避免发布后问题的发生。 如果在接口发布后发现了下面几条规则问题的发生则该模块的接口质量是比较差的。 稳定性 规则48接口废弃率/变更率越低越好 对于接口来说稳定是其最重要的属性。 这是因为接口的废弃和行为变更将极大的影响开发者的维护效率。考虑上多种设备类型、多个系统版本这个问题会变得更加复杂。 设计出能保证长期稳定持续兼容的接口是每个API设计者应当追求的目标。 接口的废弃率/变更率与接口的质量在一定程度上成反比。 安全性 规则49避免接口被滥用 所有接口在设计上应当考虑到不能被过度滥用。滥用既可能是数量上的滥用也可能是范围上的滥用。 例如对于用户公共数据相册、联系人等的访问对于长时间后台运行的能力都可能被滥用。 对于数量滥用的防止可以考虑“仅一次授权”这样的机制。 在实现上可以根据调用者的身份进行相应的限制。 当然无论是哪种限制都应该在接口说明中说明清楚。并且在检测到过度滥用的情况下有相应的返回值告知调用者。 规则50避免接口被利用 被滥用是指接口的使用超出了原先预期的限制。而被利用是指接口可以被用来造成负面影响例如攻击系统。 无论开发者以何种方式使用OpenHarmony提供的接口如果某个接口或某些接口组合调用导致系统出现了问题那么就一定接口本身存在问题。 特别的如果某些接口无论在何种情况下一旦调用就可以使用系统崩溃或者进入不能工作的场景或者能够窃取用户数据这是绝对不允许的。这就要求API的设计者从API被调用的所有可能都场景上进行考虑避免一些极端情况的发生。 可维护性 规则51能承载业务能力演进 考虑到操作系统的一些较大特性需要经过数年才能打磨完成。因此接口在设计上应当考虑今后的可扩展性。 随着能力的演进如果出现了在新版本上新起了一组新的接口而废弃了原先旧的接口那么就是接口的设计上存在问题。这是应当避免的。 规则52功能扩展后不影响原先行为 随着OpenHarmony 操作系统版本的演进一些接口新增了参数或者一些参数新增了新的选项是很常见的一种行为。 但是在这种情况下一定要考虑清楚对于过往已存在行为的一致性。不应当因为新的场景的引入而破坏了原先存在的行为。 这里需要遵循的原则是如果在新版本上行为要发生变化只允许针对目标版本是新版本的应用生效。对于目标版本是旧版本的应用应当继续保持原先的行为。 规则53文档和资料应当配套更新 当大家在更新接口实现的时候一定要记得更新接口的说明。从兼容性的角度来看不能修改原先存在的行为。通常应当提供新的接口来完成新的功能。 但在下面的情况下可以考虑修改既有接口的行为 缺陷的修复。性能/功耗的改进。为接口拓展新的特性或场景但不影响原有特性或场景逻辑。 第1、2种情况通常在Release Note里面说明第3种情况就需要在接口说明上表述清楚。 不可替代性 规则54保证API之间正交 正交Orthogonality意味着多个接口之间不应该出现重合的功能。 例如一个接口提供了创建用户账号的能力。另外一个接口包含了创建用户并登录的功能。如果是这样就应该把第二个接口拆开只保留单独登录的功能。 如果将接口的能力画成一个个图形那么这些图形之间不应该出现重叠交错的想象。对于同一个层级的接口不应该出现某个接口提供了1、2、3功能另外一个接口又提供了2、3、4功能这种情况发生。 当然为了便于调用允许将一些接口组合成一个更高阶的接口。这通常是抽象层次的不一样并非是同一个层次的重叠。 开发者反馈 规则55关注开发者反馈 尽管API在正式发布之前会经过试用阶段但考虑到试用时间和试用范围是有限的实际上无法保证能避免所有问题。 因此在接口正式发布之后也应该继续关注开发者的反馈。 开发者反馈可能分为以下几种情况 希望提供更多API来满足目前不能实现的功能这种情况可以将需求导入到下个版本的规划中。反馈API的行为与文档描述不一致这通常是缺陷应当尽快修复。如果是文档的问题也应当尽快修改。反馈接口设计不合理可能是命名或者参数设置存在问题这种情况就需要考虑API废弃同时用新API代替。 在一些情况下可能要变更已经发布的API行为。这种情况下应当要注意行为变化只能发生在新开发的应用上对于已经发布的应用不能产生行为变化。API提供者可以根据应用的目标API版本来进行判断。 在最坏的情况下需要将既存API废弃提供新的API代替。