Restful接口通用返回类示例__Java

web开发时涉及提供接口的时候，Restful接口通用返回类是系统之间交互（前后端对接，内部系统与外部系统对接等场景）时需要统一规范的定义。

然而，笔者在工作中见过许多系统对于该类的设计可谓是五花八门，杂乱无章。当前比较主流的属性结构如图所示（假设类名为RestResult）

    +-----------------------------------+
    |           RestResult              |
    +-----------------------------------+
    | - code: Integer                   |
    | - msg: String                     |
    | - data: Object                    |
    +-----------------------------------+

当然，有些系统会加一个流水号属性（每次调用的唯一标识），方便查询每次调用的具体链路及详情，结构可能与上述属性同级，也可能在data的子层级中

最为明显的分歧就是对于data属性的类别设计，很多系统在设计时喜欢将其设计成泛型，因此后续的接口层你将不得不看到这样的代码（假设类名为RestResult）

public ResponseEntity<RestResult<String>> interfaceOne() {
    // ……
}

public ResponseEntity<RestResult<Page<User>>> interfaceTwo() {
    // 返回类型这么长，这谁受得了……
}

特别是在查询分页结果的场景，这种繁琐的写法将显得尤为突出，因此个人建议大家在设计Restful接口通用返回类时，将data属性的类别设计为Object而非泛型，使用起来较为简洁优雅。

@Getter
@Setter
public class RestResult {

    private Integer code;
    private String msg;
    private Object data;

    public static RestResult ok() {
        return new RestResult(HttpStatus.OK.value(), HttpStatus.OK.name(), "");
    }

    public static RestResult ok(Object data) {
        return new RestResult(HttpStatus.OK.value(), HttpStatus.OK.name(), data);
    }

    public static RestResult err(String msg, Object data) {
        return new RestResult(HttpStatus.INTERNAL_SERVER_ERROR.value(), msg, data);
    }

    public RestResult(Integer code, String msg, Object data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }
}

使用示例

    @GetMapping("/hello")
    public ResponseEntity<RestResult> hello() {
        return ResponseEntity.ok(helloService.hello());
    }

大语言模型的观点

• 使用泛型可以提高代码的类型安全性，但会增加代码的复杂度，后期维护成本更高。
• 使用 Object 类型代码更简单，但需要在调用方进行类型转换，可能会出现类型转换错误。

个人看法

• 不推荐使用泛型，其一占用了更多系统资源（泛型会增加类和方法的元数据信息，导致内存占用增加。泛型在编译时需要进行类型擦除，这需要额外的 CPU 时间），其二会增加代码的复杂性和使用的繁琐程度
• 推荐使用Object，Object是所有类的父类，向上转型并不存在任何类型转换错误，调用方获取data向下转型时才会发生类型转换错误的可能性，但这是必要的！设计为泛型，调用方仍然需要统一data的属性结构