主键冲突应返回业务友好提示而非数据库错误，需通过sqlstate码或关键字精准识别异常，按场景定制提示文案，脱敏敏感信息并记录带请求id的warn日志。

主键冲突时的优雅提示，核心是不让用户看到“Duplicate entry”这类数据库报错，而是给出明确、可操作的业务反馈，比如“该编号已被使用，请换一个”。这需要在捕获异常后做精准识别和语义转换，而不是笼统吞掉或抛出原始异常。

精准识别主键冲突异常

不能 catch SQLException 就完事，要确认确实是主键重复。推荐方式：

• 检查异常消息中是否包含 "Duplicate entry" 和 "PRIMARY"（MySQL）或 "violates unique constraint.*pkey"（PostgreSQL）
• 用 getSQLState() 判断：MySQL 主键冲突通常为 "23000"，PostgreSQL 为 "23505"
• 避免依赖 getMessage() 全文匹配，可提取关键字做正则判断，如 "Duplicate entry.*for key 'PRIMARY'"

分场景返回不同提示

同一异常，在不同上下文应有不同响应：

Java Maven Common

Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。

下载

• 用户注册填了已存在的手机号 → 提示“该手机号已被注册，请直接登录或尝试其他号码”
• 后台导入员工编号重复 → 记录日志并返回“第127行：员工编号 8801 已存在，已跳过”
• API 接口被重复调用 → 结合幂等性校验，返回 200 + {"code":409,"msg":"请求已存在，无需重复处理"}

避免前端暴露技术细节

所有提示文案必须脱敏，禁止出现以下内容：

• 数据库表名、字段名（如 users.id）
• 错误码全称（如 SQLIntegrityConstraintViolationException）
• 堆栈信息、SQL 语句、参数值
• 建议统一用自定义业务错误码（如 10021 表示“主键已存在”），由前端映射成友好文案

配合日志做问题追溯

提示用户的同时，服务端需记录完整上下文供排查：

• 打印 WARN 级别日志，包含：请求ID、操作类型、冲突主键值、原始异常摘要
• 敏感字段（如身份证号、手机号）需脱敏后再写入日志
• 若使用 SLF4J，可加 MDC 参数，让整条链路日志可关联

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南