java-development-manual

---
name: "java-development-manual"
description: "本手册基于阿里巴巴Java开发手册（嵩山版），将规约分为7个维度。规约按约束力强弱分为："
license: "BSD-2-Clause"
---

# Java开发手册（嵩山版）

## 概述

本手册基于阿里巴巴Java开发手册（嵩山版），将规约分为7个维度。规约按约束力强弱分为：

| 级别 | 含义 | 说明 |
|------|------|------|
| **【强制】** | 必须遵守 | 违反可能导致严重问题 |
| **【推荐】** | 建议遵守 | 提升代码质量和可维护性 |
| **【参考】** | 可选择性采纳 | 根据实际情况判断 |

## 章节导航

根据需求选择对应章节的详细规约：

| 章节 | 适用场景 | 详细文档 |
|------|---------|----------|
| **编程规约** | 命名、格式、OOP、并发、集合处理 | [coding-convention.md](references/coding-convention.md) |
| **异常日志** | 错误码、异常处理、日志规范 | [exception-log.md](references/exception-log.md) |
| **单元测试** | 测试用例、覆盖率、Mock | [unit-test.md](references/unit-test.md) |
| **安全规约** | SQL注入、XSS、CSRF、脱敏 | [security.md](references/security.md) |
| **MySQL数据库** | 建表、索引、SQL、ORM | [mysql.md](references/mysql.md) |
| **工程结构** | 分层架构、依赖管理、服务器 | [project-structure.md](references/project-structure.md) |
| **设计规约** | UML、设计模式、设计原则 | [design.md](references/design.md) |

## 快速参考

### 命名规范速查

```java
// 类名：UpperCamelCase
public class UserService { }
public class UserDO { }      // DO/DTO/VO例外

// 方法名/变量：lowerCamelCase
private String userName;
public void getUserById() { }

// 常量：全大写+下划线
public static final int MAX_RETRY_COUNT = 3;

// 包名：全小写
package com.company.project.service;
```

### 禁止事项速查

| 禁止 | 原因 |
|------|------|
| 拼音命名 | 可读性差 |
| 魔法值 | 难以维护 |
| `SELECT *` | 性能和可维护性 |
| Executors创建线程池 | 可能OOM |
| 字符串拼接SQL | 注入风险 |
| finally中return | 丢失try返回值 |
| foreach中remove | ConcurrentModificationException |

### 必须事项速查

| 必须 | 原因 |
|------|------|
| 覆写方法加@Override | 避免签名错误 |
| 表必备三字段 | id, create_time, update_time |
| 敏感数据脱敏 | 隐私保护 |
| 参数校验 | 安全防护 |
| ThreadLocal回收 | 避免内存泄漏 |
| 日志用占位符 | 性能优化 |

### 异常处理速查

```java
// 正确的异常处理
try {
    // 业务逻辑
} catch (SpecificException e) {
    logger.error("操作失败, 参数: {}", params, e);
    throw new BusinessException("用户友好提示", e);
} finally {
    // 资源关闭（JDK7+ try-with-resources）
}
```

### 数据库速查

```sql
-- 建表必备
CREATE TABLE example (
    `id` bigint unsigned NOT NULL AUTO_INCREMENT,
    `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 索引命名
-- 主键: pk_字段名
-- 唯一: uk_字段名
-- 普通: idx_字段名
```

### 并发处理速查

```java
// 线程池创建
ThreadPoolExecutor executor = new ThreadPoolExecutor(
    corePoolSize,
    maximumPoolSize,
    keepAliveTime,
    TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(queueCapacity),
    new ThreadFactory() {
        private AtomicInteger counter = new AtomicInteger(1);
        public Thread newThread(Runnable r) {
            return new Thread(r, "worker-" + counter.getAndIncrement());
        }
    },
    new ThreadPoolExecutor.CallerRunsPolicy()
);

// ThreadLocal使用
try {
    threadLocal.set(value);
    // 业务逻辑
} finally {
    threadLocal.remove();  // 必须回收
}
```

## 使用指南

### 代码审查场景

1. **命名检查** → 查看 [coding-convention.md](references/coding-convention.md) 的"命名风格"章节
2. **并发问题** → 查看 [coding-convention.md](references/coding-convention.md) 的"并发处理"章节
3. **异常处理** → 查看 [exception-log.md](references/exception-log.md)
4. **安全问题** → 查看 [security.md](references/security.md)

### 新项目搭建场景

1. **架构设计** → 查看 [design.md](references/design.md)
2. **分层结构** → 查看 [project-structure.md](references/project-structure.md)
3. **数据库设计** → 查看 [mysql.md](references/mysql.md)
4. **单元测试** → 查看 [unit-test.md](references/unit-test.md)

### 问题排查场景

1. **NPE问题** → 查看 [exception-log.md](references/exception-log.md) 的"NPE防护"
2. **性能问题** → 查看 [mysql.md](references/mysql.md) 的"索引规约"
3. **并发问题** → 查看 [coding-convention.md](references/coding-convention.md) 的"并发处理"

## 能力边界

### ✅ 适用场景
- 当你需要使用此技能对应的技术栈时
- 当项目需要遵循最佳实践时
- 当需要快速上手或深入理解核心概念时

### ⚠️ 需要注意
- 复杂业务逻辑需要结合具体场景调整
- 性能优化需要根据实际数据量评估

### ❌ 不适用场景
- 不相关的技术栈或框架
- 需要完全自定义的特殊场景

## 常见陷阱 (Gotchas)

1. **版本兼容性**：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
2. **配置文件格式**：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
3. **环境变量**：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
4. **依赖冲突**：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
5. **性能陷阱**：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

## 使用流程

### Step 1: 环境准备
确保开发环境已安装必要的依赖和工具。

### Step 2: 配置初始化
根据项目需求进行基础配置。

### Step 3: 核心功能使用
按照示例代码实现核心功能。

### Step 4: 测试验证
运行测试确保功能正常。

### Step 5: 部署上线
完成开发后进行部署和监控。