Java Dev Manual Tool Free

SKILL.md

---
name: "java-dev-manual-tool-free"
description: "Java 开发规约速查手册，覆盖命名、异常、并发、数据库等 7 大维度核心规范。"
license: Proprietary
allowed-tools: read exec
compatibility: "Requires LLM with tool-use capability"
metadata:
  displayName: "Java开发手册免费版"
  version: "1.0.0"
  summary: "Java 开发规约速查手册，覆盖命名、异常、并发、数据库等 7 大维度核心规范。"
  tags:
    - "开发工具"
    - "Java"
    - "开发规范"
    - "代码质量"
  source: "SkillHub"
  converted_at: "2026-07-22T17:58:36"
---

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