java-development-manual

# 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: 部署上线 完成开发后进行部署和监控。