Oracle Helidon 项目开发规范与最佳实践指南

Oracle Helidon 项目开发规范与最佳实践指南

helidon Java libraries for writing microservices 项目地址: https://gitcode.com/gh_mirrors/hel/helidon

前言

Oracle Helidon 是一个轻量级的 Java 微服务框架，它提供了两种编程模型：Helidon SE 和 Helidon MP。本文将深入解析 Helidon 项目的开发规范与最佳实践，帮助开发者更好地理解和应用这些规则。

核心编码规范

异常处理规范

1. 使用非检查型异常：

   • 所有 API 都应该使用 RuntimeException 的子类，而非直接使用 RuntimeException
   • 仅在实现/扩展接口强制要求时才使用检查型异常
   • 适当情况下可以使用标准运行时异常，如 NoSuchElementException 和 IllegalStateException

2. 空值处理原则：

   • 公共 API 中禁止使用 null
   • 替代方案：
     • 对于设置器：提供专门的方法来移除字段值而非设置 null
     • 对于其他方法：参数较少时创建重载方法，参数多时使用构建器模式的参数对象
   • 方法返回值应使用 Optional 而非返回 null

包与模块结构

1. 扁平化包结构：

   • 每个模块（Maven 和 Jigsaw）有单一实现包
   • 可选的 "spi" 包用于服务提供者接口
   • 单元测试通过包级访问权限实现
   • 公共类及其方法将成为 Helidon API 的一部分，需谨慎维护

2. 命名规范：

   • 目录名即模块名
   • Maven 坐标：
     • 组 ID：io.helidon.${project_module}*
     • 构件 ID：helidon-${module_name}(-project)?
   • 包名：io.helidon.${project_module}*.${module_name}

配置与编程API设计

1. 配置与编程API对等原则：

   • 所有通过配置能实现的功能，必须也能通过编程方式实现
   • 反之亦然，除非需要使用反射

2. 配置键规范：

   • 使用小写字母和连字符（如 "token-endpoint-uri"）
   • 可嵌套为树形结构（如 "outbound-token.name"）
   • 配置属性分为必需、有默认值和可选三种类型

访问器方法设计

1. 简洁命名风格：

   • 不使用动词前缀，如 port(int) 和 int port()
   • 布尔类型根据可读性决定是否使用动词前缀

2. 示例：

   // 设置端口
   port(8080);
   // 获取端口
   int currentPort = port();
   

流式API设计

1. 构建器模式：

   • 所有需要参数的实例创建都应使用构建器
   • 公共API类不应使用公共构造函数

2. 构建器实现规范：

   • 必须包含私有/受保护构造函数
   • 提供静态 builder() 方法
   • 所有字段应为 final（不可变）

3. 推荐方法：

   • create() 工厂方法
   • create(Config config) 配置工厂方法

JPMS模块系统规范

1. 模块声明：

   • 每个发布的Java模块必须有 module-info.java
   • 服务声明仅在 module-info.java 中进行

2. 文档要求：

   • 为模块信息添加Javadoc
   • 使用完全限定类名声明服务和使用的服务

测试规范

1. 测试框架：

   • 使用 JUnit 5 配合 Hamcrest 断言

2. 断言风格：

   • 主要使用 assertThat(actualValue, assertion(expectedValue))
   • 常用断言：
     • is() - 相等性断言
     • notNullValue() - 非空断言
     • startsWith()/endsWith() - 字符串前缀/后缀断言

3. 异常断言：

   • 使用 assertThrows 断言异常

Maven构建规范

1. 依赖管理：

   • 所有第三方依赖版本由父POM管理
   • 添加新依赖需经过内部流程审批

2. 模块命名：

   • 项目模块：Helidon ${module_name} Project
   • Java模块：Helidon ${module_name}

3. 依赖作用域：

   • Java EE 和 MicroProfile 组件通常使用 provided 作用域
   • 仔细选择对其他 Helidon 模块的依赖作用域

结语

遵循这些开发规范不仅能保证 Helidon 项目代码的一致性和可维护性，也能帮助开发者构建出高质量的微服务应用。这些规范涵盖了从编码风格到模块设计，从异常处理到测试实践的各个方面，是 Helidon 项目成功的重要保障。

对于新加入 Helidon 生态系统的开发者，建议在开始开发前仔细阅读并理解这些规范，这将大大减少代码审查时的返工，并有助于编写出符合 Helidon 标准的优质代码。

helidon Java libraries for writing microservices 项目地址: https://gitcode.com/gh_mirrors/hel/helidon