skill分享 - Java编码规范

简介

这是一个专为 Java 开发者设计的编码规范 skill，它能让 AI 在编写或审查 Java 代码时，自动遵循统一的格式化、命名、错误处理、日志记录等最佳实践。无论是个人项目还是团队协作，这个 skill 都能确保代码风格的一致性和可维护性。

核心价值

✅ 统一代码风格：自动遵循 Google Java Style 规范
✅ 语义化命名：避免模糊的命名如 tmp、manager、helper
✅ 规范异常处理：不吞异常，保留原始错误信息
✅ 安全日志记录：避免记录敏感信息，统一使用 traceId
✅ 避免重复造轮：优先使用 JDK、Spring、Apache Commons 已有功能

如何使用

方法一：直接复制使用（推荐）

将下面的完整内容复制，发送给 Codex，告诉它"请帮我制作成 skill"即可。

方法二：手动创建 skill

如果你熟悉 skill 的创建流程，可以手动创建一个名为 java-coding-style 的 skill，并将下面的内容作为 skill 的配置。

Skill 完整内容

markdown

name: java-coding-style
description: Enforce repository-wide Java conventions for formatting, naming, error handling, logging, nullability, and documentation. Spring Web layering and API rules are defined in spring-web-api-architecture-protocol.

# Java 编码规范 (SOP)

## 适用范围（必须遵守）
在本仓库中实现或审查 Java 代码时使用此 skill。

**不适用范围：**
- Spring Web 外部 API 分层 / DTO 边界 / 验证 / 统一错误封装（使用 spring-web-api-architecture-protocol）
- 过度架构和结构极简主义规则（使用 java-code-structure-minimalism）

---

## 格式化（必须遵守）
- 代码必须可自动格式化且格式一致
- 遵循 **Google Java Style**
- 尽可能使用 `google-java-format`；不依赖手动对齐

---

## 命名语义（必须遵守）
包/类/字段/方法名称必须反映业务语义。

**禁止的命名模式：**
- **泛化或模糊名称**：`tmp`、`data`、`info`、`process`、`handle`、`doThing`、`manager`、`helper`、`util`（除非该名称是已确立的领域术语）
- **业务边界上的技术实现名称**：`Impl`、`Base`、`Common`、`Misc`（除非框架约定要求）

**命名必须在重构下保持稳定**：避免编码短暂的实现细节。

---

## 空值处理（必须遵守）
- 在相关位置保持空值处理的明确性
- 仅在返回值表示"缺失"是有效状态时使用 `Optional`；**不要在字段中使用 `Optional`**

---

## 库和工具使用（必须遵守）
当以下库中存在等效功能时，**禁止创建新的工具方法或类**：
- JDK
- Spring Framework
- Apache Commons Lang3 / Collections

**禁止：**
- 对现有库调用的薄包装
- 泛化工具类（`*Util`、`*Helper`、`*Common`）

**例外：**
- 仅当辅助方法编码业务语义（非泛化逻辑）且被重用时，才允许使用辅助方法

---

## 异常处理和验证（必须遵守）
- **绝不吞掉异常**
- 重新抛出时保留原始原因
- 明确分类错误：
  - **领域错误**：表示业务规则违反
  - **基础设施错误**：IO/DB/远程调用/超时
- **不要将异常消息用作程序逻辑**
- 在模块边界强制执行不变量

---

## 日志记录和可观测性（必须遵守）
- **不要记录敏感信息**：密钥、凭据、令牌或 PII
- 日志必须携带关联标识符，使用一致的 MDC 键，例如 `traceId`

**日志级别：**
- **ERROR**：需要关注的意外故障
- **WARN**：可恢复的异常或降级行为
- **INFO**：业务相关的状态转换（避免在热路径）
- **DEBUG/TRACE**：仅用于本地调试

**避免在热路径产生噪音日志**；在循环/重试中限流日志。

---

## 注释和 Javadoc（必须遵守）
- **文档语言默认为简体中文**，除非明确要求其他语言
- 为公共类和公共方法编写简洁的 Javadoc（当行为不明显时）
- 仅在非明显的分支或不变量处使用内联注释
- 对于简单的仅测试代码，可以放宽 Javadoc 要求

### 类级 Javadoc 头（添加新公共类时必须）
包含：

/**
 * @author heidi
 * @date yyyy/MM/dd
 * @describe <简短的描述>
 * @since 1.0
 */

---

## 审查检查清单（必须遵守）
- ☑ 代码已通过 `google-java-format`（或等效的自动格式化工具）格式化
- ☑ 名称具有业务语义且无歧义
- ☑ 空值处理在需要的地方是明确的
- ☑ 异常未被吞掉；原因已保留
- ☑ 日志排除敏感信息/PII 并包含 `traceId`
- ☑ 注释/Javadoc 默认使用简体中文

使用建议

适用场景：Java 项目开发或代码审查时，让 AI 自动遵循此规范
调用方式：在对话中告诉 Codex"使用 java-coding-style skill"
最佳实践：
- 在项目初期就引入此 skill，保持代码风格一致
- 结合团队约定调整具体规则
- 定期检查 AI 生成的代码是否符合规范

skill分享 - Java编码规范 ​

简介 ​

核心价值 ​

如何使用 ​

方法一：直接复制使用（推荐） ​

方法二：手动创建 skill ​

Skill 完整内容 ​

使用建议 ​

相关资源 ​