当前位置:首页 > Java >

Java API最佳实践

PDF超清英文版

时间:2020-10-12 20:48:31大小:417 KB已被710人关注 资源下载

Java API实例应用
Java API实例应用

最近在做接口对接的工作,发现要写出一个双方都满意的api并不是一件容易的事,刚好在DZone 上看到微软工程师 Jonathan Giles 写的一篇文章,学到了一些经验,便做了翻译或许可以帮助到更多的开发者。

作为一个开发者,我们工作就是每天写代码,当然我们不可以脱离于其他人而写代码。可以确定的是我们都在踩在前人的肩膀上进行学习工作,今天有大量的工具可以供我们使用,比如github,stack overflow,maven central,还有很多可用的第三方库可以供我们使用,软件是在api(Application Programming Interfaces)基础上创造的,我们使用大量来自Maven或者Gradle的第三方库。
如果我们询问工程师们他们是不是API开发者,他们通常会回答不是,但是这个回答有不正确的,工程师只要曾经精心写出过public的类或者public的方法,就可以被看作是api开发者。

“精心”这个形容词是必要的,API的设计就像一件艺术品,需要创造力并且需要付出很时间,同时更像是一门科学。

API风格

API风格有很多衡量的标准,下面介绍6点标准。

容易理解的

你有多少次通过maven下载依赖的第三方库后,确不知道从那个类开始使用这个api? 一个设计优秀的api应该让使用者很直观的理解应该如何使用它。

api开发者应该思考如果让使用者找到api的使用入口。完整的文档是帮助使用者理解api的全貌,但更理想的是在文档的开始处,使用最精炼的描述使使用者可以以小步迭代的方式学会使用api。
因此,优秀的api试图通过使用入口暴露他们的功能点,使用者通过使用api start case而产生兴趣,然后通过文档掌握更多的功能特性。

良好的注释

我们希望他人使用我们的api,因此我们需要努力把文档做好.

代码风格一致性

一个好的api不应该使它的使用者感到意外,没有保持一致性便会使使用者感到意外。

一致性是指我们在api中重复相同的风格,比如:

3.1 所有方法使用getXYZ() 或者 xyz(),而不是同时使用两种形式

3.2 如果有两个方法(一个是另一个的重载,比如一个参数为Object…,

而另一个是Collectio)Collecti<? extends Object>),那么这种方式的重载风格需要保持下去。

关键是在整个SDK的开发过程中我们需要确立一个小组一致赞成的术语规范和一个备忘录来确保风格一致性。

实现确定的目标

开发api,我们必须确定满足用户的需求。可以从下面两个方式思考:

4.1 只做一件事情,并且做好

4.2 理解你的用户和他们的潜在目标

JDK中的Collections API就是一个好的栗子,用户可以方便的利用集合存储数据和取出数据,而不需要自定义集合扩展条件、工厂、增加策略、hash碰撞策略、比较策略、缓存、负载系数等。开发者在使用集合的功能时甚至不需要了解其框架内部是如何工作的。

有约束的

新增一个API或许会很快,但是我们应当尽力理解这个api,因为以后很可能会花很多时间来对这个api进行维护。

对api的使用主要来自我们的项目和社区,一些项目经常做出一些破坏性的变更,然而像JDK本身的api很少出现紧急的变更。

很多api会在中途被放弃,在api被移除之前使用一个语义上放弃的标志是一个合适的方式。

一个项目在最终版本确定之前会使用很多标志来表明试验版、beta版、或者预习功能以备回滚使用。

一个通常的做法在api被考虑周全之前使用@Deprecated标志或者清楚该标志来表明功能是否可以使用。

可维护的

我们开发的每一个api,都是以开发者角度而不是用户的角度来确定其使用范围的。当我们确定api的使用范围时,必须花一些时间去验证在更宽广的上文中使用我们的sdk.

已被919人点赞
Java 日志封装 API
Java 日志封装 API

除了 JUL 和 log4j 这样的日志记录库之外,还有一类库用来封装不同的日志记录库。这样的封装库中一开始以 Apache Commons Logging 框架最为流行,现在比较流行的是 SLF4J。这样封装库的 API 都比较简单,只是在日志记录库的 API 基础上做了一层简单的封装,屏蔽不同实现之间的区别。由于日志记录实现所提供的 API 大致上比较相似,封装库的作用更多的是达到语法上的一致性。

在 Apache Commons Logging 库中,核心的 API 是 org.apache.commons.logging.LogFactory 类和 org.apache.commons.logging.Log 接口。LogFactory 类提供了工厂方法用来创建 Log 接口的实现对象。比如 LogFactory.getLog 可以根据 Java 类或名称来创建 Log 接口的实现对象。Log 接口中为 6 个不同的严重性级别分别定义了一组方法。比如对 DEBUG 级别,定义了 isDebugEnabled()、debug(Object message) 和 debug(Object message, Throwable t) 三个方法。从这个层次来说,Log 接口简化了对于日志记录器的使用。

SLF4J 库的使用方式与 Apache Commons Logging 库比较类似。SLF4J 库中核心的 API 是提供工厂方法的 org.slf4j.LoggerFactory 类和记录日志的 org.slf4j.Logger 接口。通过 LoggerFactory 类的 getLogger 方法来获取日志记录器对象。与 Apache Commons Logging 库中的 Log 接口类似,Logger 接口中的方法也是按照不同的严重性级别来进行分组的。Logger 接口中有同样 isDebugEnabled 方法。不过 Logger 接口中发出日志记录请求的 debug 等方法使用 String 类型来表示消息,同时可以使用包含参数的消息,如清单 4 所示。

清单 4. SLF4J 的使用方式

public class Slf4jBasic { 
private static final Logger LOGGER = LoggerFactory.getLogger(Slf4jBasic.class); 
public void logBasic() { 
if (LOGGER.isInfoEnabled()) { 
LOGGER.info("My log message for %s", "Alex"); 
} 
} 
}

 

已被607人点赞
Java API学习总结
Java API学习总结

Java 日志 API

从功能上来说,日志 API 本身所需求的功能非常简单,只需要能够记录一段文本即可。API 的使用者在需要进行记录时,根据当前的上下文信息构造出相应的文本信息,调用 API 完成记录。一般来说,日志 API 由下面几个部分组成:

记录器(Logger):日志 API 的使用者通过记录器来发出日志记录请求,并提供日志的内容。在记录日志时,需要指定日志的严重性级别。

格式化器(Formatter):对记录器所记录的文本进行格式化,并添加额外的元数据。

处理器(Handler):把经过格式化之后的日志记录输出到不同的地方。常见的日志输出目标包括控制台、文件和数据库等。

已被674人点赞
下载地址:百度网盘下载
相关资源
Java jdk12 API官方文档(jdk13帮助文档)
Java jdk12 API官方文档(jdk13帮助文档) 完整版

Java12 API文档,记录Java12语言中的类、方法、接口信息。目前官方最新版本jdk13,是这里提供 Java12 API官方文档CHM版和jdk13帮助文档html完整版 ,都是官方英文版的,需要的朋友可下载试试! ps:另外请查看右键-属性-解除锁定,否则点击 右边框不会显示相应内容 JDK13到今天已经发布快3个月了,之前有零零散散的试过一些新的特性,但却没有整体的整理一下。想到作为Java开发,连使用的JDK(Java Developerment Kit)有什么特性都不清楚,实在是有些不应

立即下载
Spark 2.2.x API 中文参考文档+Spark java developers
Spark 2.2.x API 中文参考文档+Spark java developers 高质量版

Spark 2.2.x Doc API 中文参考文档, 本教程是对使用 Spark 的一个简单介绍。首先我们会通过 Spark 的交互式 shell 简单介绍一下 (Python 或 Scala) API,然后展示如何使用 Java、Scala 以及 Python 编写一个 Spark 应用程序。 Spark Shell 提供了一种简单的方式来学习 Spark API,同时它也是一个强大的交互式数据分析工具。Spark Shell 既支持 Scala(Scala 运行在 Java 虚拟机上,所以可以很方便

立即下载
Java jdk14 API官方帮助文档
Java jdk14 API官方帮助文档 高清版

Java14 文档,记录Java14语言中的类、方法、接口信息。目前官方最新版本jdk14,这里提供Java14 API官方文档官方英文版,需要的朋友可下载试试! 3月17日JDK 14 正式发布了,此版本包含的 JEP(Java/JDK Enhancement Proposals,JDK 增强提案)比 Java 12 和 13 加起来的还要多。 总共 16 个新特性如下: 305:Pattern Matching for instanceof (Preview) 为 instanceof 运算符引入模式

立即下载

Copyright 2018-2020 www.xz577.com 码农之家

版权投诉 / 书籍推广 / 赞助:520161757@qq.com