# unified-response

**Repository Path**: sky007z/unified-response

## Basic Information

- **Project Name**: unified-response
- **Description**: 在网络 API 开发过程中，需要返回的信息往往不仅仅是业务数据，还应有状态码，错误码等提示信息，它们在接口交互中扮演着重要的角色，为了解决这个问题，我们需要一个统一的、易于使用的响应结果格式
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-01-13
- **Last Updated**: 2024-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
	<img alt="logo" src="https://amaris-picgo.oss-cn-hangzhou.aliyuncs.com/img/head.png">
</p>
<h1 align="center" style="margin: 10px 0 10px; font-weight: bold;">UnifiedResponse v1.0.2</h1>
<h4 align="center">基于 Spring Boot 统一响应实现方案</h4>




## 应用场景
在实际系统中，作为服务端，我们返回的信息往往不仅是客户端需要的数据，还需要能够在各种异常发生时提供异常原因等反馈信息，这在客户端和服务端之间的交互中起着重要的作用。
## 怎样的结构
```json
{
    "code": "B0001",
    "message": "服务端发生未知错误",
    "tip": "服务器发生错误啦！",
    "data": "java.lang.NullPointerException"
}
```
> 该结构由 5 个部分组成（参考阿里 java 开发手册）
> 1. status(http 状态码)：面向浏览器
>
>    其中，status 已嵌入到  Http 响应状态行中，未在具体返回结果中显示
>
> 2. code(错误码)：面向前端人员
>
> 3. message(错误信息)：面向排错人员
>
> 4. tip(用户提示信息)：面向用户
>
> 5. data(数据对象)：待返回给前端的数据

## 如何使用

### 依赖引入

```xml
<!-- https://mvnrepository.com/artifact/cn.codepandas/unified-response -->
<dependency>
    <groupId>cn.codepandas</groupId>
    <artifactId>unified-response</artifactId>
    <version>1.0.2</version>
</dependency>
```

### 使用 `@UnifiedResponse` 注解
在需要包装成统一响应结构的类或方法上使用`@UnifiedResponse`注释，当然，这些类或方法都应在controller层中

```java
 @UnifiedResponse
 @RestController
 public class HelloController {
 
     @GetMapping("/hello")
     public String sayHello(){
         return "hello!";
     }
     
 }
```

## 关于异常的处理
抛出异常，UnifiedResponse 机制会自动捕获该异常，并将其包装成统一的响应结构体

```java
public void test(){
	try {
	int n = 1/0;
	} catch (ArithmeticException e){
		throw e;
	}
}
```

在所提供的 ResultException 类的帮助下，您还可以根据具体的业务场景自定义异常并抛出

```java
public void test(){
    try {
        int n = 1/0;
    }catch (ArithmeticException e){
        throw new ResultException(ResultCode.SERVER_ERROR);
    }
}
```

## 关于 ResultCode
ResultCode 包括 status、code 和 message，决定响应结果的内容。它可以是 ResultException 构造方法的形参。
下面是两种使用 ResultCode 的方法。

### 使用提供的 result-codes
已经提供的 result-code 包括 `SUCCESS`, `CLIENT_ERROR`, `SERVER_ERROR` and `SERVICE_ERROR`, 
你可以通过 ResultCode 类使用它们，比如 `ResultCode.SUCCESS`

```java
/**
* 正常
*/
SUCCESS(200, "00000", "一切正常", "一切正常，请继续操作！"),

/**
* 客户端错误
*/
CLIENT_ERROR(400, "A0001", "客户端发生错误", "客户端发生错误啦！"),

/**
* 服务端错误
*/
SERVER_ERROR(500, "B0001", "服务端发生错误", "服务器发生错误啦！"),

/**
* 第三方服务调用错误
*/
SERVICE_ERROR(500, "C0001", "第三方服务发生错误", "第三方服务发生错误啦！");
```
### 自定义 result-codes
要为您的项目自定义 result-code ，您需要通过实现 IResultCode 接口，例如:

```java
public class CustomizedResultCode implements IResultCode{
    
    private final Integer status;
    private final String code;
    private final String message;
    private final String tip;

    ResultCode(Integer status, String code, String message, String tip) {
        this.status = status;
        this.code = code;
        this.message = message;
        this.tip = tip;
    }

    @Override
    public Integer getStatus() {
        return status;
    }

    @Override
    public String getCode() {
        return code;
    }

    @Override
    public String getMessage() {
        return message;
    }

    @Override
    public String getTip() {
        return tip;
    }
}
```

## 版本迭代说明

> 未来优化方向：
>
> - 考虑是否需要校验参数异常等业务相关内容
> - 优化 pom 依赖
> - 与  Spring 解耦，不基于框架实现

### 当前版本 v1.0.2

- 完善 IResultCode 注释

### 历史版本

| 版本号 | 迭代内容                                                     |
| ------ | ------------------------------------------------------------ |
| v1.0.1 | 优化 pom 依赖                                                |
| v1.0.0 | 修改项目名称；优化结果码设计方案；支持参数异常的处理；解决 String 作为返回类型产生的异常 |