# coufran-spring-boot-starter-api

**Repository Path**: coufran/coufran-spring-boot-starter-api

## Basic Information

- **Project Name**: coufran-spring-boot-starter-api
- **Description**: Spring stareter：API
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-05-19
- **Last Updated**: 2025-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Spring, SpringBoot, API, lib, Java

## README

# 作用
1. 移除了``spring-boot-starter-web``默认的Jackson（``spring-boot-starter-json``）依赖，使用Fastjson（``coufran-spring-boot-starter-json``）担当原本Jackson的作用。
2. 引入``coufran-commons``的标准结果``Result``和标准错误``ServiceException``。
3. 业务结果和异常自动包装，业务Controller可以直接返回data或抛出Exception。

# 基本用法
## 引入依赖
使用coufran-spring-boot-starter-api替换spring-boot-starter-web。
```xml
<dependency>
    <groupId>cn.coufran</groupId>
    <artifactId>coufran-spring-boot-starter-api</artifactId>
    <version>3.0.0</version>
</dependency>
```

## 使用标准结果和标准错误
Controller可以直接返回业务结果或抛出异常，例如：

```java
@RestController
public class DemoController {
    /*
    直接返回业务结果，收到的消息：
    {
        "success": true,
        "code": "200",
        "message": "成功",
        "data": "Hello,Coufran!"
    }
     */
    @RequestMapping("/demoResult")
    public String demoResult() {
        return "Hello,Coufran!";
    }

    /*
    发生业务错误直接抛出异常，收到的消息：
    {
        "success": false,
        "code": "50001",
        "message": "测试错误"
    }
     */
    @RequestMapping("/demoError")
    public String demoError() {
        throw new ServiceException(50001, "测试错误");
    }
}
```
不需要自动包装时，可以直接返回``Result``对象或使用``@NoWrap``标记接口。
```java
@RestController
public class DemoController {
    @RequestMapping("/result")
    public Result result() {
        return Result.ok(20001);
    }

    @RequestMapping("/result")
    @NoWrap
    public String result() {
        return "Hello,Coufran!";
    }
}
```
# 高级用法
## JPA（Hibernate）lazy load属性的处理
JPA（Hibernate）lazy load属性在脱离EntityManager的管理之后，如无法被加载，序列化时会被忽略。
> 如果需要被序列化，请务必在EntityManager还在的时候，手动get触发加载。

## Fastjson处理循环引用
Fastjson序列化循环引用对象时，默认使用``$ref``指针指向重复对象。
> 浏览器无法处理``$ref``引用可以使用工具函数转换，详见[本人CSDN博客](https://blog.csdn.net/Coufran/article/details/118363399)

## 自定义Fastjson序列化配置
``coufran-spring-boot-starter-api``提供了默认的FastJson配置，如需自定义，可以声明一个类型为``FastJsonConfig``的Bean。
```java
@Configuration
public class DemoJsonConfig {
    @Bean
    public FastJsonConfig fastJsonConfig() {
        FastJsonConfig fastJsonConfig = new FastJsonConfig();
        // xxxx
        return fastJsonConfig;
    }
}
```

## 自定义业务异常
``coufran-spring-boot-starter-api``默认使用与``coufran-spring-boot-starter-log``相同的业务异常配置Bean，如果需要单独添加，可以使用``ExceptionHandler.addServiceExceptionClass()``方法。
```java
@Configuration
public void DemoConfig(){
    @Resource
    private ExceptionHandler exceptionHandler;

    @PostConstruct
    public void demoConfig(){
        exceptionHandler.addServiceExceptionClass(XxxException.class);
    }
}
```

# 版本历史
## v3.0.0（2025-08-11）
1. 升级到Spring Boot 3。

## v2.0.1（2022-11-28）
1. 修复枚举类响应值错误的Bug。

## v2.0.0（2022-11-01）
1. 优化异常处理。

## v1.3.0（2022-05-20）
1. 优化依赖。
2. 增加业务异常的配置。

## v1.2.0（2021-07-01）
1. 增加对Hibernate lazy load属性的支持。
2. 增加Fastjson自定义配置。
3. 优化Result API。

## v1.1.1（2021-05-20）
1。 修正已知Bug。

## v1.1.0（2020-12-06）
1. 增加标准结果Result和标准错误ServiceException。
2. 业务结果自动包装，业务Controller可以直接返回data。
3. 修正已知Bug。

## v1.0.0（2020-08-04）
1. 使用Fastjson替换Jackson。