评价api好坏的标准.ppt
,3.1 方法和字段签名 3.2 文件及其内容 3.3 环境变量和命令行选项 3.4 文本信息也是api 3.5 协议 3.6 行为 3.7 国际化支持和信息国际化,第3章 评价api好坏的标准,3.8 api的广泛定义 3.9 如何检查api的质量 3.9.1 可理解性 3.9.2 一致性 3.9.3 可见性 3.9.4 简单的任务应该有简单的方案 3.9.5 保护投资,评价api好坏的标准,API设计,误解：API只是加对类和方法提供说明的JAVADOCAPI存在的原因：可以将大块的构件“无序”地集合应用程序构件模块：包括共享类库、框架、预先定义的应用程序框架、及上述的组合。每个API完全正确，程序集成工作就简单。不存在调试、阅读代码、打补丁和如何设计。是“无绪”的编程,API构件模快,构件模块：(1)共享类库(2)框架(3)预先定义的应用程序框架(4)上述的组合。每个API完全正确，程序集成工作就简单。,程序集成工作就简单,表现：(1)不用阅读代码要求(2)不要编写代码(3)不用调试模块功能(4)不用打补丁,3.1方法和字段的签名,一个API是一堆类以及类方法和字段（属性）的集合。涉及成员方法问题：涉及公共的成员，包括数据成员、受保护成员、私有成员。如何访问成员涉及模块内部相关问题。,对公共成员访问,公开成员：对所有公共（公开）成员访问，只需要访问相应的名称对非公开的成员访问涉及比较复杂，非公开的成员（内容），未公开的内容简介不是API，表示它不外承诺兼容性。,未公开的内容访问,对非公开成员访问，一般使用反射技术来创建对象时，不需要知道具体类型，只需要的话字符串的方式传入类的全名即可创建 一个实例对象。反射是直接读入dll或者对应的库，反射机制是取出模块中所有的中间语言代码,反射机制有两个用处,程序集设计者本身在程序集发布后由于某些需求想调用原先的私有方法，进行某些操作 程序集的使用者恶意的使用私有成员作一些本身 out of scope by design 的事情。反射可以访问对象所有成员当然包括私有的，所以这种做法是很危险的,3.2文件及其内容,应用程序执行时要读写的文件夹以及这些事文件的格式非常重要。配置信息也是一类重要的API。对外通过虚拟方式提供配置文件可以保持一致性，这是配置文件很重要的优点。,3.3环境变量和命令行选项,环境变量和命令行界面作为上下文环境，对于 功能的库来说，往往不是很重要。接口在特定环境下也是非常重要。不是所有的操作系统的都提供了环境变量方面的功能,Java处理方式,缺少一种读取环境变量的方法需要的读取当前的环境变量值，然后编写脚本调用前面的所说的那些命令取代方案：系统属性。Java中的任何方法都是可以用调用System.getProperty方法，通过传入一个字符串名称来读取 与属性相关的值。,3.4文本信息也是API,很多程序不仅可以通过环境变量和命令行参数进行控制，还可以向一段程序输入一段文本作为参数并取得一个返回值。Unixe 有一个很大的特点，就是它合用了管道技术。管道是从一个程序进程向另一个程序进单向传送信息的技术。,toString方法的误用,toString返回的字符串URL格式，试图让用户知道，如果不要取得路径应该调用getPath方法。程序员员想知道错误发生的地方，只能得到到输出的错误信息，然后再去解析输出设备的错误文本信息。,3.5协议,协议是针对文本内容的API。它们用来定义网络传送中的信息格式，所以非常重要。协议访问控制问题：对于一个对外开放的套接字来说，其实访问是没有办法进行控制的。另一个问题是因使用网络协议而被放大，每个网络协议会有多种客房端，协议有多个版本和程序进行交互，且这种多样性还会不断扩散。,3.5协议不一致性问题,服务器上的Subversion软件版本与客户端计算机上所使用的版本不一致。版本不一致问题协议不一致问题。协议演进问题。版本要向后兼容扩张性和通用性问题。,3.6行为,API可避免去了解一个组件内部具体实现，可以使用其他的黑盒程序模块来组装自己的程序。不论API的抽象度有多好，API对应的内部实现经常会泄露具体的内容。从而使得这些内部实现也变成了API的一部分对外公开尽管API具体行为很难控制，但它仍是API契约中非常重要、甚至最重要的一部分。只有组件的行为能够保证稳定，其用户在组装程序时，才能做到用“无绪”方式来替换一个模块。,3.7国际化支持和信息国际化,很多API设计，并不会考虑到所有人的需求不同的API会有不同的目标受众有人非常关注这些对于这些就是合适的、感兴趣的API。很多开发人员都是针对一个功能的类库进行编码的，从这样的一个API普通用户的角度来看，这是国际化信息中的键值是一个底层的实现。,3.8API的广泛定义,API远远不止是类、方法、函数和签名这些东西。为了有利于在“无绪”的状态下把一个大的系统组件集成的方式拼装出来，从这个角度来看，API的定义就非常广泛，从简单的文本信息到那些复杂或者很难控制的组件行为，都可以算是API。,3.9如何检查API的质量,漂亮并不是衡量API的唯一标准。工程的首要目标是制作可正常运作的系统。我们应该设计易于使用、广泛接受且富有成效的API。可理解性一致性可见性,可理解性,API是设计者与开发人员之间交流的途径后者要根据相应的的API提供具体实现。程序员的沟通方式就是API。涉及的概念必须处于用户的视野范围内，否则他们就无法理解这些概念。API设计者需要理解其目标用户普遍上具有的知识，并且在此类知识的基础上设计API。,可理解性,开始人员都使用过大部分Java的类库因此也了解其涉及的概念。很多API用户都会去找一个现有的程序，这个程序的功能要与现在要开发的功能比较相似，然后把这个程序的代码复制过来，再加以调整来完成自己现在开发的功能。那么提花大量的例子能够有效地帮助大家使用API,一致性,API有不念旧恶很重要的评价标准，而且也很容易进行检查，那就是一致性。在整个API的开发过程中最好保持一致性的风格，至少对API进行演进时一定要保持一致。,可见性,有人想使用某个API，但根本找不到这个API，或者很难清楚地了解这个API如何使用，那么这个API再漂亮也没什么用。为什么时候开源软件如此成功，因为在使用开源软件时，通常只需要把现有的一些源代码复制过来就可以开始工作了。有一个入口来作为用户开始使用API的起点为，可以帮助用户找到正确的方式来解决他们的问题。,简单任务应该有简单方案,不同用户群共用一个API。设计API时最容易也是最常犯的错误就是把针对不同受众的功能都放在不一个API中。降低程序员的可见性，某些开发人员只关心API某一方面的功能。常用语方案是把一个API分解成两个或者多个组成部分：一部分是针对调用功能的开发人员，而另一部分则应该放在贸易逆差的包中，或者有其特有的命名空间，用来方便扩展当前模块的功能,保护投资,要使用一个类库，那么就要去了解它，砍它能够减少自己的工作量，而不是带来更多的问题。对于API设计者来说，首要的任务就是要保护其用户投入的资源。还有一种不严格使用类库的模式，则会带来更多的灵活性，比如说获取源有代码，然后修正问题，再重新编译。这样做在开源世界里很常见，对于Linux，比如说把方法的名称改一下使清楚，调整一下API的结构使之更易理解,
