# speedcar-base-spring-boot-starter

**Repository Path**: hack-feng/speedcar-base-spring-boot-starter

## Basic Information

- **Project Name**: speedcar-base-spring-boot-starter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-31
- **Last Updated**: 2025-12-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# speedcar-base-spring-boot-starter

## 简介

`speedcar-base-spring-boot-starter` 是一个基于 Spring Boot 的基础 Starter 模块，为 SpeedCar 项目提供通用的基础功能和配置。该模块封装了常用的工具类、异常处理、国际化支持等核心功能，简化了业务模块的开发。

## 功能特性

- 🌍 国际化支持 (i18n)
- ⚠️ 统一异常处理
- 🛠️ 统一返回参数封装
- 🔧 基础配置自动装配
- 📝 日志统一管理

## 快速开始

### 依赖引入

在您的 [pom.xml](file://D:\code\speedcar-base-spring-boot-starter\pom.xml) 中添加以下依赖：

```xml
<dependency>
    <groupId>com.speedcar</groupId>
    <artifactId>speedcar-base-spring-boot-starter</artifactId>
    <version>2.0.1</version>
</dependency>
```


### 配置文件

在 `application.yml` 中添加项目名称和日志位置的基础配置：

```yaml
spring:
    application:
        name: third-api
        
logging:
    file:
        path: /data/logs/test/third-api
```

## 核心功能

### 1. 国际化支持

#### 配置国际化资源文件

必须是 `.properties` 文件，且文件名必须为 `messages_`加对应语言代码。

在 `src/main/resources/i18n/` 目录下创建资源文件：

```
src/main/resources/
└── i18n/
    ├── messages.properties          # 默认语言
    ├── messages_zh_CN.properties    # 简体中文
    └── messages_en.properties       # 美式英语
```


#### 使用国际化工具类

```java
// 获取国际化消息
String message = ScI18nUtils.get("error.unknown");

// 获取带参数的国际化消息
String message = ScI18nUtils.get("error.user.notfound", "userId");
```


### 2. 统一异常处理

#### 自定义异常基类

```java
// 继承 SpeedCarBaseException 创建业务异常
public class UserNotFoundException extends SpeedCarBaseException {
    ......
}
```

#### 使用方法

继承自 SpeedCarBaseException的示例，以下是几种常见的使用方法：

1. 定义具体的业务异常类

```java
// 继承 SpeedCarBaseException 创建具体的业务异常
public class UserNotFoundException extends SpeedCarBaseException {
    public UserNotFoundException(String userId) {
        super("error.user.notfound", userId);
    }
}
```
2. 在业务逻辑中抛出异常

```java
@Service
public class UserService {
    
    public User getUserById(String userId) {
        User user = userRepository.findById(userId);
        if (user == null) {
            // 抛出自定义业务异常
            throw new UserNotFoundException(userId);
        }
        return user;
    }
    
    public void updateUser(User user) {
        if (user.getAge() < 0) {
            throw new SpeedCarBusinessException(ErrorCode.COMMON_ERROR, "error.user.age.invalid");
        }
        userRepository.save(user);
    }
}
```

## 3. 结合国际化使用

首先在国际化资源文件中定义错误信息：

messages.properties:
```properties
error.user.notfound=用户未找到: {0}
error.user.age.invalid=用户年龄无效
```

messages_en.properties:
```properties
error.user.notfound=User not found: {0}
error.user.age.invalid=Invalid user age
```

然后在代码中使用：

```java
// 抛出带参数的异常，自动从国际化资源中获取消息

import com.speedcar.base.exception.ErrorCode;

throw new SpeedCarBusinessException(ErrorCode.COMMON_ERROR, "error.user.notfound",userId);

// 或者抛出不带参数的异常
throw new SpeedCarBusinessException(ErrorCode.COMMON_ERROR, "error.user.age.invalid");
```

4. 在控制器中使用

```java
@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @Autowired
    private UserService userService;
    
    @GetMapping("/{userId}")
    public ResultJson getUser(@PathVariable String userId) {
        try {
            User user = userService.getUserById(userId);
            return ResultJson.success(user);
        } catch (UserNotFoundException e) {
            // 异常会被统一异常处理机制捕获并转换为统一格式返回
            throw e;
        }
    }
}
```

### 3. 自定义返回类型

默认格式
~~~json
{
  "status": true,
  "code": "200",
  "message": "",
  "data": {}
}
~~~

重写ScResultWrapper，可覆盖依赖中默认的返回类型

~~~java

import com.speedcar.base.result.ScResultWrapper;
import com.speedcar.common.model.ResultJson;
import org.springframework.stereotype.Component;

@Component
public class ThirdApiResultWrapper implements ScResultWrapper {
    @Override
    public Object wrap(Object body) {
        return new ResultJson(body);
    }

    @Override
    public Object wrapException(String code, String message) {
        return new ResultJson(code, message);
    }
}
~~~

### 4. 统一日志管理

使用logback日志，保存在logging.file.path目录下
命名格式为spring.application.name_xxx.log
以天为单位，次日生成新的日志文件，前一天文件压缩归档，保留近30天的日志文件。

~~~
xxxxxx_detail.log
xxxxxx_debug.log
xxxxxx_error.log
~~~

#### 使用方法

方法级别的日志会监听@SpeedCarLog注解，方法调用会记录日志
~~~java
@SpeedCarLog(value = "上传文件")
public String test() {
    return "测试日志";
}
~~~

## 版本历史

### 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


## 联系方式

项目维护者：SpeedCar 技术团队

如有问题，请提交 Issue 或联系技术支持。