# api-result

**Repository Path**: joyz/api-result

## Basic Information

- **Project Name**: api-result
- **Description**: 统一返回结果扩展插件，集成消息的国际化、格式化功能
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-10-30
- **Last Updated**: 2024-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= API Result

image:https://img.shields.io/badge/Release-1.0.0-blueviolet[Release Version] 
image:https://img.shields.io/badge/License-Apache%202.0-blue[Apache 2.0 License] image:https://img.shields.io/badge/Build by-gradle-green[Build toolkit] image:https://img.shields.io/badge/Build by-Adoptium OpenJDK 1.8-ff69b4[jdk]

统一返回结果扩展插件，集成消息的国际化、格式化功能

== 安装

maven::
[source,xml]
.pom.xml
----
<dependencies>
   <dependency>
       <groupId>io.gitee.joyz</groupId>
       <artifactId>api-result</artifactId>
       <version>1.0.0</version>
   </dependency>
</dependencies>
----

Gradle::
[source,gradle]
.build.gradle
----
dependencies {
    implementation 'io.gitee.joyz:api-result:1.0.0'
}
----


== 如何配置？

首先, 使用该扩展需要进行一些简单的初始化配置工作. 扩展提供了 `ResultContextHolder` 类用于配置各项参数. 该类采用了单例模式, 仅支持通过 `ResultContextHolder.instance()` 方法获取其唯一实例.
用户可以在程序入口位置进行初始化工作

示例::
[source,java]
.ApplicationStarter.java
----
public class ApplicationStarter {

    public static void main(String[] args) {

        ResultContextHolder holder = ResultContextHolder.instance();
        holder.setBaseName("resourceBundlePath");
        holder.setDefaultEncoding(StandardCharsets.UTF_8.name());
        holder.setLocaleSupplier(LocaleContextHolder::getLocale);
    }
}
----

=== 配置项说明

[[setDefaultStatus]] setDefaultStatus::
|===
|方法|默认值|说明
|setDefaultStatus(ResultStatus status)
|-
|配置默认的状态枚举, 当用户未指定状态时, 系统会默认返回该状态枚举中的状态码和消息文本
|===


[[setDefaultEncoding]] setDefaultEncoding::
|===
|方法|默认值|说明
|setDefaultEncoding(String encoding)
|ISO-8859-1
|配置资源包文件的默认编码
|===

[[setLocaleSupplier]] setLocaleSupplier::
|===
|方法|默认值|说明
|setLocaleSupplier(Supplier<Locale> localeSupplier)
|-
|配置动态 (Locale) 实例获取, 系统支持在每次进行消息解析时动态的获取一个 Locale 实例, 常用于适配多语言应用WEB项目
|===

Spring boot 示例:
[source,java]
.Configuration.java
----
public class Configuration {

    @Bean
    public ResultContextHolder holder () {
        ResultContextHolder holder = ResultContextHolder.instance();
        holder.setLocaleSupplier(LocaleContextHolder::getLocale);
        return holder;
    }
}
----


[[setDefaultLocale]] setDefaultLocale::
|===
|方法|默认值|说明
|setDefaultLocale(Locale locale)
|-
|配置一个默认的语言环境. 如果配置了该项, 当解析消息时未传入 Locale 实例, 则使用该默认语言环境
|===


[[setBaseName]] setBaseName::
|===
|方法|默认值|说明
|setBaseName(String baseName)
|-
|配置一个资源包路径
|===
[WARNING]
该配置会将之前设置的所有资源包路径清除


[[setBaseNames]] setBaseNames::
|===
|方法|默认值|说明
|setBaseNames(String... baseNames)
|-
|配置多个资源包路径
|===
[WARNING]
该配置会将之前设置的所有资源包路径清除


[[addBaseNames]] addBaseNames::
|===
|方法|默认值|说明
|addBaseNames(String... baseNames)
|-
|增加多个资源包路径
|===
[TIP]
该配置不同于 <<setBaseName, setBaseName>>, <<setBaseNames, setBaseNames>> 配置, 该配置不会清除之前配置的资源包路径


[[setCacheTime]] setCacheTime::
|===
|方法|默认值|说明
|setCacheTime(int seconds)
|-1 (永久)
|配置加载的资源包缓存过期时间. 单位: 秒
|===


[[setFallbackToSystemLocale]] setFallbackToSystemLocale::
|===
|方法|默认值|说明
|setFallbackToSystemLocale(boolean isFallback)
|false
|配置是否允许回退至系统语言环境. 在用户未使用 <<setDefaultLocale, setDefaultLocale>> 配置默认语言环境的情况下, 当解析消息时未传入 Locale 实例, 系统则会根据该配置选择是否使用系统语言环境
|===
[WARNING]
在 Web 项目环境中, 由于服务器系统语言环境与客户端语言环境完全无关, 所以可能存在服务器语言环境和客户端语言环境不一致的情况. 所以Web项目环境中推荐将该属性值设置为 `false`


[[setParent]] setParent::
|===
|方法|默认值|说明
|setParent(LocaleMessage parent)
|-
|配置一个父消息组件实例, 当消息无法找到且设置了父消息组件的情况下, 系统会继续尝试使用父消息组件解析消息
|===


[[setUseCodeAsDefaultMessage]] setUseCodeAsDefaultMessage::
|===
|方法|默认值|说明
|setUseCodeAsDefaultMessage(boolean useCodeAsDefaultMessage)
|false
|设置当消息无法解析时, 是否允许使用消息代码作为消息返回
|===


== 自定义返回结果

扩展提供了默认的返回结果类 `ResultVo`. 其返回结果格式为:

[source,json]
----
{success: true, code: 200, msg: "message info", data=data}
----

如果扩展提供的默认返回结果类无法满足您的项目需求, 可以自定义返回结果类. 自定义返回结果类必须实现 `Resultant` 或 `ResultantData` 接口

|===
|接口|说明

|Resultant
|接口提供了序列化能力和 状态码 (Status code) 和 消息文本 (Message text) 属性

|ResultantData
|接口继承自 `Resultant` 接口, 并额外提供了 data 属性
|===

[TIP]
推荐继承 `ResultantData` 接口, 因为绝大部分应用的返回结果中不仅仅要包含业务状态码和消息, 更重要的是还需要返回一组数据.

示例::
[source,java]
.TestResultVO.java
----
public class TestResultVO<T> implements ResultantData<T> {

    private static final long serialVersionUID = 3757428157042327509L;

    /**
     * 状态码
     */
    private Integer status;

    /**
     * 消息
     */
    private String desc;

    /**
     * 载荷
     */
    private T record;

    /**
     * 时间戳
     */
    private long timestamp;

    @Override
    public void setCode(Integer code) {
        this.status = code;
    }

    @Override
    public void setMsg(String msg) {
        this.desc = msg;
    }

    @Override
    public void setData(T data) {
        this.record = data;
    }

    @Override
    public T getData() {
        return record;
    }

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

    @Override
    public String getMsg() {
        return desc;
    }

    public long getTimestamp() {
        return timestamp;
    }

    public void setTimestamp(long timestamp) {
        this.timestamp = timestamp;
    }
}
----

== 消息枚举
在实际开发中, 业务状态码及消息都是事前约定好的. 如果每次封装返回结果时都需要手动输入业务状态码和消息不但容易出错, 这对于后期的维护也带来了极大的不便. 因此, 扩展允许用户对状态消息进行统一模板化封装

=== 自定义消息枚举类
系统提供了 `ResultantStatus` 接口用于扩展消息模板，自定义消模板类必须是一个 *枚举* 类型

示例::
[source,java]
.TestResultStatus.java
----
public enum TestResultStatus implements ResultantStatus {
    SUCCESS(2000, "test.success"),
    HI(2001, "test.hi"),
    HELLO(2002, "Hello~ {0}"),
    FAILED(4000, "Request failed");

    /**
     * 状态码
     */
    private final Integer status;

    /**
     * 消息
     */
    private final String message;

    TestResultStatus(final Integer status, final String message) {
        this.status = status;
        this.message = message;
    }


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

    @Override
    public String getMsg() {
        return message;
    }
}
----

[TIP]
根据项目的实际需求, 如果项目需要实现消息国际化, 那么 `message` 属性可以设置为对应消息的 key. 消息文本可以设置参数, 扩展支持对消息的格式化功能.


=== 设置默认消息
系统提供 <<setDefaultStatus, setDefaultStatus>> 方法允许将一个消息枚举作为为默认返回的功能. +
在实际项目中, 都有操作成功的响应状态. 如果用户将成功的状态枚举设置为默认后, 以后每次成功请求用户都无需再手动传入该状态参数

示例::
[source,java]
.ApplicationStarter.java
----
public class ApplicationStarter {

    public static void main(String[] args) {

        ResultContextHolder holder = ResultContextHolder.instance();

        // 设置默认消息枚举
        holder.setDefaultStatus(TestResultStatus.SUCCESS);
    }

}
----

== 国际化支持
如果项目中需要国际化支持且已经自定义了状态消息模板类, 切记要通过 <<setBaseName, setBaseName>> 或 <<setBaseNames, setBaseNames>> 或 <<setBaseName, addBaseNames>> 方法配置对应的资源包路径, 否则系统将无法获取到对应的国际化消息

== 自定义工具类
系统为我们提供了 `ResultUtils` 工具类用于快速构建 Result 实例，您也可以根据自己的项目需求参考 `ResultUtils` 自定义封装

== LICENSE

API Result is open Source software, released under the link:./LICENSE[Apache 2.0 license].