exception-logging-standards

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

异常日志规约技能

作用

本技能基于《阿里巴巴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. 正例参考