Java Dev Manual Tool Free

Java 开发规约速查手册，覆盖命名、异常、并发、数据库等 7 大维度核心规范。

Java 开发手册（免费版）

概述

本工具为 Java 开发者提供开发规约的速查能力，覆盖编程规约、异常日志、单元测试、安全规约、数据库规约、工程结构、设计规约共 7 大维度。规约按约束力强弱分为【强制】、【推荐】、【参考】三级，帮助开发者编写规范、可维护的 Java 代码。免费版聚焦个人开发者的规约速查场景，提供简明的速查表与代码示例。

核心能力

维度	描述	规约数量
编程规约	命名、格式、OOP、并发、集合	20+ 条
异常日志	错误码、异常处理、日志规范	10+ 条
单元测试	测试用例、覆盖率、Mock	8+ 条
安全规约	SQL 注入、XSS、CSRF、脱敏	8+ 条
数据库规约	建表、索引、SQL、ORM	15+ 条
工程结构	分层架构、依赖管理	8+ 条
设计规约	UML、设计模式、设计原则	6+ 条
技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置。

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 按照skill规范执行核心功能执行操作,遵循单一意图原则。 输出: 返回核心功能执行的执行结果,包含操作状态和输出数据。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。 输出: 返回参数配置与调用的执行结果,包含操作状态和输出数据。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。 输出: 返回结果处理与输出的执行结果,包含操作状态和输出数据。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Java、开发规约速查手册、覆盖命名、数据库等、大维度核心规范、开发者的开发规约、速查工具、大维度的规约指引、大维度规约速查、命名规范、格式规范、规范速查、并发处理与集合操、作规范、异常处理与日志规、范模板等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：命名规范查询

开发者编写代码时需要查询命名规范。

text

用户：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;

禁止：
- 拼音命名（如 yonghuMing）
- 中英文混合
- 使用下划线（常量除外）

场景二：并发处理规范查询

开发者需要查询线程池和 ThreadLocal 的使用规范。

text

用户：线程池创建和 ThreadLocal 使用的规范

助手：
线程池创建规范：
- 【强制】禁止使用 Executors 创建线程池（可能 OOM）
- 【强制】使用 ThreadPoolExecutor 显式创建

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 使用规范：
- 【强制】使用后必须 remove，避免内存泄漏

try {
    threadLocal.set(value);
    // 业务逻辑
} finally {
    threadLocal.remove();
}

场景三：数据库建表规范查询

开发者需要查询数据库建表和索引命名规范。

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_字段名

-- 禁止事项
-- 禁止 SELECT *
-- 禁止字符串拼接 SQL
-- 禁止使用存储过程处理业务逻辑

不适用场景

以下场景Java开发手册免费版不适合处理：

• 无明确技术栈的模糊需求
• 纯架构设计决策
• 运维部署管理

触发条件

需要代码生成、编程辅助、调试测试、开发部署时使用。不适用于非本工具能力范围的需求。

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

禁止事项速查

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

必须事项速查

必须	原因
覆写方法加 @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）
}

// try-with-resources
try (Connection conn = dataSource.getConnection();
     PreparedStatement stmt = conn.prepareStatement(sql)) {
    // ...
} catch (SQLException e) {
    logger.error("数据库操作失败", e);
    throw new RuntimeException(e);
}

序号	错误场景	原因	处理方式	优先级
1	输入参数缺失	用户未提供必要参数	提示用户提供所需参数后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令	P0
2	执行超时	处理时间过长	检查输入数据量,分批处理	P1
3	输出格式错误	结果不符合预期格式	检查output_format参数配置	P1

示例

命名规范速查表

类型	规范	正确示例	错误示例
类名	UpperCamelCase	UserService	userService
方法名	lowerCamelCase	getUserById()	GetUserById()
变量名	lowerCamelCase	userName	user_name
常量	全大写下划线	MAX_RETRY	maxRetry
包名	全小写	com.company.service	com.Company.Service
枚举	UpperCamelCase	HttpStatus.OK	HttpStatus.ok

日志规范速查

java

// 使用 SLF4J 占位符（不要用字符串拼接）
logger.info("用户登录: userId={}", userId);

// 异常日志必须包含堆栈
logger.error("操作失败: {}", params, e);  // e 作为最后一个参数

// 日志级别使用规范
logger.debug("调试信息: {}", detail);    // 调试
logger.info("用户注册: {}", userId);      // 重要业务
logger.warn("缓存未命中: {}", key);       // 告警
logger.error("数据库异常", e);            // 错误

// 禁止
System.out.println("...");               // 禁止使用控制台输出
logger.info("用户" + userId + "登录");    // 禁止字符串拼接

集合操作速查

java

// 集合转 Map 的正确方式
Map<Long, User> userMap = userList.stream()
    .collect(Collectors.toMap(User::getId, u -> u));

// 指定初始容量
Map<String, String> map = new HashMap<>(expectedSize / 0.75 + 1);
List<String> list = new ArrayList<>(expectedSize);

// 安全的删除方式
// 错误
for (User u : userList) {
    if (u.getStatus() == 0) {
        userList.remove(u);  // ConcurrentModificationException
    }
}

// 正确
Iterator<User> it = userList.iterator();
while (it.hasNext()) {
    if (it.next().getStatus() == 0) {
        it.remove();
    }
}

// 或使用 removeIf
userList.removeIf(u -> u.getStatus() == 0);

最佳实践

1. 常量代替魔法值：所有硬编码值提取为常量

   java

   public static final int STATUS_ACTIVE = 1;
   

2. 使用 try-with-resources：自动管理资源关闭

3. 异常信息包含上下文：便于问题定位

   java

   throw new BusinessException("用户[" + userId + "]不存在");
   

4. 日志用占位符：避免不必要的字符串拼接

5. 集合指定初始容量：减少扩容开销

6. 参数校验前置：在方法入口校验参数

7. 避免在循环中创建对象：减少 GC 压力

8. 使用 Optional 替代 null：更安全地处理空值

常见问题

Q1：为什么禁止使用 Executors？

java

// Executors.newFixedThreadPool() 使用无界队列，可能 OOM
ExecutorService executor = Executors.newFixedThreadPool(10);
// 内部使用 new LinkedBlockingQueue<>()，队列无上限

// 正确：使用 ThreadPoolExecutor 并指定有界队列
ExecutorService executor = new ThreadPoolExecutor(
    10, 10, 0L, TimeUnit.MILLISECONDS,
    new LinkedBlockingQueue<>(1000)  // 有界队列
);

Q2：foreach 中为什么不能 remove？

java

// foreach 使用 Iterator 遍历
// remove 会修改 modCount，导致 ConcurrentModificationException

// 正确方式一：Iterator.remove()
Iterator<User> it = list.iterator();
while (it.hasNext()) {
    if (condition) it.remove();
}

// 正确方式二：removeIf
list.removeIf(u -> condition);

Q3：如何正确处理 NPE？

java

// 使用 Optional 避免空指针
public String getUserName(User user) {
    return Optional.ofNullable(user)
        .map(User::getName)
        .orElse("未知用户");
}

// 集合返回空集合而非 null
public List<User> getUsers() {
    return Collections.emptyList();  // 不返回 null
}

// 字符串判空
if (StringUtils.isNotBlank(name)) { }

Q4：数据库索引怎么建？

sql

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

-- 索引原则
-- 1. 查询频繁的字段建索引
-- 2. 区分度高的字段优先
-- 3. 避免过多索引（影响写入性能）
-- 4. 联合索引遵循最左前缀原则

-- 示例
CREATE INDEX idx_user_status ON users(status, create_time);
-- 支持查询: WHERE status = ?
-- 支持查询: WHERE status = ? AND create_time > ?
-- 不支持:   WHERE create_time > ?

Q5：日志级别怎么选？

级别	使用场景	示例
ERROR	影响业务功能的错误	数据库连接失败
WARN	可预期的异常，不影响主流程	缓存未命中
INFO	重要的业务操作	用户注册、订单创建
DEBUG	调试信息	方法参数、中间结果
TRACE	详细执行流程	SQL 执行详情

Q6：如何做参数校验？

java

// 使用 JSR-303 注解校验
public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;
    
    @Min(value = 0, message = "年龄不能为负数")
    private Integer age;
    
    @Email(message = "邮箱格式不正确")
    private String email;
}

// Controller 中使用
@PostMapping("/users")
public Result create(@Valid @RequestBody UserDTO dto) {
    // dto 已通过校验
}

依赖说明

运行环境

• Agent 平台: 支持读取 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统: Windows / macOS / Linux
• JDK 版本: 建议 8 及以上

依赖详情

依赖项	类型	是否必需	获取方式
JDK	编译器/运行时	推荐	oracle.com 或 openjdk.net 下载
SLF4J	日志框架	推荐	maven 中央仓库
Lombok	工具库	可选	maven 中央仓库
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

• 本工具为纯 Markdown 指令驱动，无需额外 API Key
• 代码编译验证需要 JDK 环境

可用性分类

• 分类: MD+EXEC（Markdown 指令 + 命令行执行）
• 说明: 通过自然语言指令驱动 Agent 提供规约查询与代码建议，编译验证需要 JDK 执行能力

已知限制

• 需LLM支持,无LLM环境不可用
• 复杂业务场景建议结合人工经验判断
• 执行效率受模型能力与网络环境影响
• 当前为免费版本,如需完整功能请升级到付费版获取全部能力