# Alibaba Java Guidelines

> 阿里巴巴Java开发规范（黄山版）编码指导技能。当用户在编写Java代码、进行代码审查、设计数据库表结构、处理异常日志、编写单元测试、设计系统架构时，必须使用此技能来确保代码符合阿里巴巴Java开发规范。触发词：Java开发规范、阿里规范、p3c、代码规范、命名规范、Java编码、单元测试规范、数据库设计规范、并发编程、异常处理规范、日志规范。适用于所有Java项目开发，帮助大模型生成符合规范的代码。

- Skill: `tzf1003/alibaba-java-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tzf1003/alibaba-java-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tzf1003/alibaba-java-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tzf1003 (https://skillmd.com/u/tzf1003)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tzf1003/alibaba-java-guidelines

---


# 阿里巴巴Java开发手册（黄山版）编码规范技能

## 概述

本技能基于《阿里巴巴Java开发手册（黄山版）》，指导在Java开发中遵循统一的编码规范。规约分三级：
- **【强制】**：必须遵守，违反会导致严重后果
- **【推荐】**：尽量遵守，提升代码质量
- **【参考】**：理解原则，结合实际情况使用

## 规范体系总览

本技能涵盖七大维度，详细规则见各参考文件：

| 维度 | 文件 | 内容 |
|------|------|------|
| 一、编程规约 | `references/01-programming.md` | 命名、常量、格式、OOP、日期、集合、并发、控制语句、注释、前后端、其他 |
| 二、异常日志 | `references/02-exception-logging.md` | 错误码、异常处理、日志规约 |
| 三、单元测试 | `references/03-unit-testing.md` | 单元测试规范 |
| 四、安全规约 | `references/04-security.md` | 安全编码规范 |
| 五、MySQL数据库 | `references/05-mysql.md` | 建表、索引、SQL、ORM映射 |
| 六、工程结构 | `references/06-project-structure.md` | 应用分层、二方库依赖、服务器配置 |
| 七、设计规约 | `references/07-design.md` | 系统设计规范 |

## 快速参考：最高频强制规则

### 命名规范（必读）
- 类名用 `UpperCamelCase`（DO/DTO/BO/VO例外）
- 方法名、变量名用 `lowerCamelCase`
- 常量全大写，单词间下划线：`MAX_STOCK_COUNT`
- 包名全小写、单数形式
- 抽象类以 `Abstract`/`Base` 开头；异常类以 `Exception` 结尾；测试类以 `Test` 结尾
- POJO布尔类型变量**不加** `is` 前缀
- Service/DAO 实现类后缀 `Impl`

### 代码格式（必读）
- 4空格缩进，禁止使用Tab
- 单行不超过120字符
- 单方法不超过80行
- 大括号不换行：`if (x) {`
- 运算符两侧加空格

### OOP关键规则（必读）
- 覆写方法必须加 `@Override`
- 不能使用 `==` 比较Integer，必须用 `equals()`
- 浮点数比较用 `BigDecimal` 或误差范围
- 禁止 `new BigDecimal(double)`，用 `new BigDecimal("0.1")` 或 `BigDecimal.valueOf(0.1)`
- POJO类属性必须用**包装类型**，局部变量用基本类型
- POJO必须写 `toString()` 方法
- Object的 `equals` 用常量在前：`"test".equals(param)` 而非 `param.equals("test")`

### 并发关键规则（必读）
- 禁止用 `Executors` 创建线程池，必须用 `ThreadPoolExecutor`
- `SimpleDateFormat` 不能是static，或用 `ThreadLocal`；推荐JDK8 `DateTimeFormatter`
- `ThreadLocal` 必须在 `finally` 中 `remove()`
- 双重检查锁中目标属性必须声明为 `volatile`

### 集合关键规则（必读）
- 判空用 `isEmpty()` 而非 `size() == 0`
- `foreach` 循环中禁止 `remove/add`，用 `iterator`
- `toArray` 必须传入 `new String[0]`
- `Collections.emptyList()` 返回的是不可变集合

## 如何使用本技能

生成Java代码时，按照以下步骤：

1. **命名阶段**：参照 `references/01-programming.md` 的命名风格部分
2. **代码实现**：参照对应的OOP规约、集合处理、并发处理规则
3. **数据库操作**：参照 `references/05-mysql.md`
4. **异常处理**：参照 `references/02-exception-logging.md`
5. **安全相关**：参照 `references/04-security.md`

当用户要求审查代码时，逐项检查上述规范并给出具体改进建议，标注违反的规则等级（强制/推荐/参考）。