Java开发手册免费版

Java 开发手册（免费版）

概述

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

核心能力

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

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

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

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

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

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

使用场景

场景一：命名规范查询

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

用户：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 的使用规范.

用户：线程池创建和 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();
}

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

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

-- 建表必备字段
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解答常见疑问

禁止事项速查

必须事项速查

错误处理

// 正确的异常处理
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);
}

示例

命名规范速查表

日志规范速查

// 使用 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 + "登录");    // 禁止字符串拼接

集合操作速查

// 集合转 Map 的正确方式
Map userMap = userList.stream()
    .collect(Collectors.toMap(User::getId, u -> u));
// ...
// 指定初始容量
Map map = new HashMap<>(expectedSize / 0.75 + 1);
List list = new ArrayList<>(expectedSize);
// ...
// 安全的删除方式
// 错误
for (User u : userList) {
    if (u.getStatus() == 0) {
        userList.remove(u);  // ConcurrentModificationException
    }
}
// ...
// 正确
Iterator it = userList.iterator();
while (it.hasNext()) {
    if (it.next().getStatus() == 0) {
        it.remove();
    }
}
// ...
// 或使用 removeIf
userList.removeIf(u -> u.getStatus() == 0);

最佳实践

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

   public static final int STATUS_ACTIVE = 1;
   

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

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

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

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

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

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

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

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

常见问题

Q1：为什么禁止使用 Executors？

// 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？

// foreach 使用 Iterator 遍历
// remove 会修改 modCount，导致 ConcurrentModificationException
// ...
// 正确方式一：Iterator.remove()
Iterator it = list.iterator();
while (it.hasNext()) {
    if (condition) it.remove();
}
// ...
// 正确方式二：removeIf
list.removeIf(u -> condition);

Q3：如何正确处理 NPE？

// 使用 Optional 避免空指针
public String getUserName(User user) {
    return Optional.ofNullable(user)
        .map(User::getName)
        .orElse("未知用户");
}
// ...
// 集合返回空集合而非 null
public List getUsers() {
    return Collections.emptyList();  // 不返回 null
}
// ...
// 字符串判空
if (StringUtils.isNotBlank(name)) { }

Q4：数据库索引怎么建？

-- 索引命名
-- 主键: pk_字段名
-- 唯一: uk_字段名
-- 普通: idx_字段名
# ...
-- 索引原则
-- 1. 查询频繁的字段建索引
-- 2. 区分度高的字段优先
-- 3. 避免过多索引（影响写入性能）
-- 4. 联合索引遵循最左前缀原则
# ...
-- 示例
CREATE INDEX idx_user_status ON users(status, create_time);
-- 支持查询: WHERE status = ?
 AND create_time > ?
-- 不支持:   WHERE create_time > ?

Q5：日志级别怎么选？

Q6：如何做参数校验？

// 使用 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 及以上

依赖详情

API Key 配置

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

可用性分类

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

已知限制

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

输出格式

{
  "success": true,
  "data": {
    "result": "Java开发手册免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "java dev manual"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}