# Exception Logging Standards

> 阿里巴巴Java开发手册 — 异常日志规约审查与指导。当用户涉及以下任何场景时触发： - 设计错误码体系、定义错误码规范 - 异常处理策略设计、try-catch规范 - 日志输出规范、日志级别使用 - 错误信息分层设计（error_code / error_message / user_tip） - Java异常处理代码审查（RuntimeException、NPE等） - 第三方服务错误码转义 - 用户提到"错误码"、"异常处理"、"日志"、"error code"、"log"等关键词 此技能适用于所有编程语言，错误码设计和日志规范是通用能力。

- Skill: `greenplumwine/exception-logging-standards` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add greenplumwine/exception-logging-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/greenplumwine/exception-logging-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Greenplumwine (https://skillmd.com/u/greenplumwine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/greenplumwine/exception-logging-standards

---


# 异常日志规约技能

## 作用

本技能基于《阿里巴巴Java开发手册》的异常日志章节，为开发者提供错误码设计、异常处理和日志规范的指导。

涵盖以下领域：

| 规约领域 | 说明 |
|---------|------|
| 错误码设计 | 错误码格式、来源分类、编号规范 |
| 异常处理 | 异常捕获原则、NPE防护、事务回滚 |
| 日志规约 | 日志级别、输出规范、异常日志记录 |

## 使用方法

1. **代码审查** — 输入：异常处理或日志相关代码；执行：按需读取 `references/` 下对应规约文件后逐条检查；输出：按【强制】【推荐】【参考】分级的问题清单 + 正例参考
2. **规范设计** — 输入：业务场景或现有错误码/日志规范描述；执行：引用 `references/error-code.md` 或 `references/logging-rules.md`；输出：设计方案 + 编号示例 + 分层建议
3. **第三方错误码转义** — 输入：第三方接口文档或现有转义映射；执行：引用错误码设计规约；输出：转义方案 + 映射表模板

## 日志审查检查点

执行异常日志规约审查时，以下场景需先向用户确认，再执行后续操作：

| 场景 | 检查内容 |
|------|---------|
| 建议修改错误码体系 | 涉及已有错误码的变更时，确认影响范围并提醒兼容性风险 |
| 建议调整日志级别 | 生产环境日志级别变更前，确认当前日志量和存储容量 |
| 用户未提供代码 | 提示用户粘贴异常处理或日志相关代码，说明审查覆盖范围 |
| 涉及第三方错误码转义 | 确认第三方接口版本和现有转义映射，避免重复或冲突 |

## 边界条件处理

| 场景 | 处理方式 |
|------|---------|
| 用户未提供代码 | 提示用户粘贴异常处理或日志相关代码，说明审查覆盖范围 |
| 日志框架差异（Logback/Log4j2/JUL） | 日志规约原则通用，但具体配置语法（如 async appender）需按用户实际框架调整 |
| 错误码体系已固化 | 在现有体系基础上给出优化建议，不推荐推倒重来，除非有兼容性迁移方案 |
| 分布式系统日志 | 提示用户关注 traceId 串联和日志集中采集，超出单进程日志规约范围需额外说明 |
| references 文件缺失 | 基于通用异常日志原则给出建议，提示检查 references 目录完整性 |

## 规约文件索引

所有规约原文存放于 `references/` 目录下，按小节拆分，按需读取：

```
references/
├── error-code.md          # 错误码设计规约（格式、来源、编号）
├── exception-handling.md  # 异常处理规约（捕获原则、NPE、事务）
└── logging-rules.md       # 日志规约（级别、输出、记录规范）
```

### 按需读取指引

| 任务类型 | 需要读取的规约文件 |
|---------|------------------|
| 设计错误码体系 | error-code.md |
| 审查异常处理代码 | exception-handling.md |
| 审查日志代码 | logging-rules.md |
| 全面审查 | 按涉及领域逐个读取 |

## 规约等级说明

原文中的规约分为三个等级：
- **【强制】**：必须遵守
- **【推荐】**：建议遵守
- **【参考】**：供参考

## 审查输出格式

1. **【强制】违规项**
2. **【推荐】改进项**
3. **【参考】优化建议**
4. **正例参考**