# spring-exception-i18n

**Repository Path**: ZiQiStudio/spring-exception-i18n

## Basic Information

- **Project Name**: spring-exception-i18n
- **Description**: 一个强大的 Spring Boot Starter，专为 **Spring Boot 3.x+** (Spring Framework 6.x+) 设计，为基于 ProblemDetail 和 ErrorResponse 接口的异常处理提供完整的国际化支持。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-01
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot Starter Exception I18N v3.0.1

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Spring Boot 3.2+](https://img.shields.io/badge/Spring%20Boot-3.2+-green.svg)](https://spring.io/projects/spring-boot)
[![Java 17+](https://img.shields.io/badge/Java-17+-orange.svg)](https://www.oracle.com/java/)
[![Version](https://img.shields.io/badge/Version-3.0.1-blue.svg)](https://gitee.com/sagi/spring-exception-i18n)

一个强大的 Spring Boot Starter，专为 **Spring Boot 3.x+** (Spring Framework 6.x+) 设计，为基于 ProblemDetail 和 ErrorResponse 接口的异常处理提供完整的国际化支持。

## 📋 目录

- [项目结构](#项目结构)
- [模块说明](#模块说明)
- [快速开始](#快速开始)
- [使用说明](#使用说明)
- [示例代码](#示例代码)
- [版本历史](#版本历史)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 🏗️ 项目结构

```
spring-exception-i18n-parent (v3.0.1)
├── pom.xml                           # 父模块 POM（版本管理）
├── README.md                         # 项目说明文档
│
├── spring-boot-starter-exception-i18n/   # 🚀 国际化组件模块
│   ├── pom.xml                           # 组件模块配置
│   └── src/main/
│       ├── java/studio/ziqi/spring/extend/exception/i18n/
│       │   └── ExceptionI18nAutoConfiguration.java
│       └── resources/
│           ├── META-INF/spring.factories
│           ├── exception-messages.properties (中文)
│           ├── exception-messages_en.properties (英文)
│           ├── exception-messages_zh_CN.properties (中文)
│           ├── exception-messages_ja_JP.properties (日语)
│           └── exception-messages_ko_KR.properties (韩语)
│
└── spring-exception-i18n-demo/          # 📦 测试/示例模块
    ├── pom.xml                           # 示例模块配置
    └── src/main/
        ├── java/example/
        │   ├── Application.java
        │   ├── config/WebConfig.java
        │   ├── controller/UserController.java
        │   └── exception/UserNotFoundException.java
        └── resources/
            ├── application.yml
            └── exception-messages_zh_CN.properties
```

## 📦 模块说明

### 1. spring-boot-starter-exception-i18n（可部署）

**国际化组件模块** - 这是核心的 Spring Boot Starter，提供异常国际化功能。

**特性**：
- ✅ 自动配置 MessageSource
- ✅ 支持 ProblemDetail 和 ErrorResponse
- ✅ 内置 30+ Spring 内置异常的国际化
- ✅ 支持 4 种语言（中英日韩）
- ✅ 所有依赖设置为 optional，避免冲突
- ✅ 可独立部署到 Maven 仓库



- 完整的国际化Key格式：基于Spring Framework 6.x的ErrorResponse接口
- RFC 7807标准：包含ProblemDetail的type URI链接
- 多语言支持：英文、中文、日语、韩语
- 参数化消息：支持占位符 {0}, {1} 等
- 详细的注释：每个异常类都包含源码信息和HTTP状态码

**Maven 坐标**：
```xml
<dependency>
    <groupId>io.gitee.ziqistudio</groupId>
    <artifactId>spring-boot-starter-exception-i18n</artifactId>
    <version>3.0.1</version>
</dependency>
```

### 2. spring-exception-i18n-demo（不可部署）

**测试/示例模块** - 演示如何使用国际化组件，包含完整的示例代码和测试用例。

**特性**：
- ✅ 完整的 Spring Boot 应用示例
- ✅ 自定义异常实现示例
- ✅ 控制器和配置类
- ✅ 单元测试和集成测试
- ✅ 启动脚本和部署说明

**用途**：
- 学习如何使用 Starter
- 验证功能是否正常
- 测试不同语言支持
- 参考最佳实践

## 🚀 快速开始

### 在你的项目中添加依赖

```xml
<dependency>
    <groupId>io.gitee.ziqistudio</groupId>
    <artifactId>spring-boot-starter-exception-i18n</artifactId>
    <version>3.0.1</version>
</dependency>
```

### 运行示例项目

```bash
cd spring-exception-i18n-demo
mvn spring-boot:run
```

### 测试国际化功能

```bash
# 测试中文
curl -H "Accept-Language: zh-CN" http://localhost:8080/api/users/details/999

# 测试英文
curl -H "Accept-Language: en-US" http://localhost:8080/api/users/details/999

# 测试日语
curl -H "Accept-Language: ja-JP" http://localhost:8080/api/users/details/999

# 测试韩语
curl -H "Accept-Language: ko-KR" http://localhost:8080/api/users/details/999
```

## 📚 使用说明

### 自动配置

添加依赖后，Starter 会自动配置：

1. **MessageSource**：加载国际化资源文件
2. **异常处理**：自动国际化 ErrorResponse 异常
3. **语言检测**：基于 Accept-Language 头选择语言

### 资源文件位置

```
exception-messages.properties          (默认，中文)
exception-messages_en.properties    (英文)
exception-messages_zh_CN.properties    (简体中文)
exception-messages_ja_JP.properties    (日语)
exception-messages_ko_KR.properties    (韩语)
```

### 自定义资源文件

在项目的 `src/main/resources` 目录下创建同名文件即可覆盖：

```properties
# 自定义覆盖 exception-messages_zh_CN.properties
problemDetail.title.org.springframework.web.HttpRequestMethodNotSupportedException=自定义标题
problemDetail.org.springframework.web.HttpRequestMethodNotSupportedException=自定义消息：{0}
```

## 💻 示例代码

### 实现 ErrorResponse 接口

```java
public class UserNotFoundException extends RuntimeException implements ErrorResponse {

    private final Long userId;

    public UserNotFoundException(Long userId) {
        this.userId = userId;
    }

    @Override
    public ProblemDetail getBody() {
        ProblemDetail problemDetail = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        problemDetail.setType(URI.create("https://example.com/errors/user-not-found"));
        problemDetail.setTitle("User Not Found");
        problemDetail.setDetail(String.format("User with id %d not found", userId));
        return problemDetail;
    }

    @Override
    public HttpStatusCode getStatusCode() {
        return HttpStatus.NOT_FOUND;
    }

    @Override
    public Object[] getDetailMessageArguments() {
        return new Object[]{userId};
    }
}
```

### 控制器中使用

```java
@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        throw new UserNotFoundException(id);  // 自动国际化
    }
}
```

### 响应示例

**中文响应**：
```json
{
  "type": "https://example.com/errors/user-not-found",
  "title": "用户未找到",
  "detail": "ID 为 999 的用户未找到",
  "status": 404
}
```

**英文响应**：
```json
{
  "type": "https://example.com/errors/user-not-found",
  "title": "User Not Found",
  "detail": "User with id 999 not found",
  "status": 404
}
```

## 🔄 版本历史

### v3.0.1 (2026-01-01)

#### 🎯 重大变更

**模块化架构**：
- ✅ 重构为多模块 Maven 项目
- ✅ 分离组件模块和示例模块
- ✅ 明确部署边界（组件可部署，示例不可部署）

**技术改进**：
- ✅ 优化依赖管理（dependencyManagement）
- ✅ 改进构建配置（plugins management）
- ✅ 增强文档结构

**兼容性**：
- ✅ 继续支持 Spring Boot 3.2+
- ✅ 继续支持 Spring Framework 6.x+
- ✅ 保持 Java 17+ 要求

#### 📝 变更详情

**新增模块**：
- `spring-boot-starter-exception-i18n` - 国际化组件（可部署）
- `spring-exception-i18n-demo` - 测试示例（不可部署）

**配置优化**：
- 父模块统一版本管理
- 组件模块支持发布（Javadoc、Source、GPG）
- 示例模块禁用发布配置

**文档更新**：
- 新增项目结构说明
- 优化模块说明
- 改进使用指南

### v1.0.0

初始版本，包含完整的异常国际化功能。

## 🤝 贡献指南

我们欢迎所有形式的贡献！

### 贡献流程

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 开发指南

**环境要求**：
- Java 17+
- Maven 3.6+
- Spring Boot 3.2+

**构建项目**：
```bash
# 构建所有模块
mvn clean install

# 仅构建组件模块
mvn clean install -pl spring-boot-starter-exception-i18n -am

# 运行测试
mvn test

# 运行示例应用
cd spring-exception-i18n-demo
mvn spring-boot:run
```

## 📄 许可证

本项目采用 Apache 2.0 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Spring Framework](https://spring.io/projects/spring-framework) - 提供强大的企业级 Java 应用开发框架
- [Spring Boot](https://spring.io/projects/spring-boot) - 简化 Spring 应用的开发
- [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807.html) - HTTP API 错误响应标准

## 📞 联系我们

- 项目主页：https://gitee.com/ziqistudio/spring-exception-i18n
- 问题反馈：https://gitee.com/ziqistudio/spring-exception-i18n/issues
- 邮箱：sagi@example.com

---

**⭐ 如果这个项目对你有帮助，请给它一个星标！**