字节都在用的代码自动生成

左手的ㄟ右手 2024-03-17 12:39 42阅读 0赞

### 背景 ###

如果有一份接口定义，前端和后端都能基于此生成相应端的代码，不仅能降低前后端沟通成本，而且还能提升研发效率。

字节内部的 RPC 定义主要基于 thrift 实现，thrift 定义了数据结构和函数，那么是否可以用来作为**接口定义**提供给前端使用呢？如果可以作为接口定义，是不是也可以通过**接口定义**自动生成请求接口的代码呢？答案是肯定的，字节内部已经衍生出了多个基于 thrift 的代码生成工具，本篇文章主要介绍如何通过 thrift 生成前端接口调用的代码。

### 接口定义 ###

接口定义，顾名思义就是用来定义接口的语言，由于字节内部广泛使用的 thrift 基本上满足接口定义的要求，所以我们不妨直接把 thrift 当成接口定义。

thrift 是一种跨语言的远程过程调用 (RPC) 框架，如果你对 Typescript 比较熟悉的话，那它的结构看起来应该很简单，看个例子：

namespace go namesapce
    
    // 请求的结构体
    struct GetRandomRequest {
        1: optional i32 min,
        2: optional i32 max,
        3: optional string extra
    }
    
    // 响应的结构体
    struct GetRandomResponse {
        1: optional i64 random_num
    }
    
    // 定义服务
    service RandomService {
       GetRandomResponse GetRandom (1: GetRandomRequest req)
    }

示例中的 service 可以看成是一组函数，每个函数可以看成是一个接口。我们都知道，对于 restful 接口，还需要定义接口路径（比如 /getUserInfo）和参数（query 参数、body 参数等），我们可以通过 **thrift 注解**来表示这些附加信息。

namespace go namesapce
    
    struct GetRandomRequest {
        1: optional i32 min (api.source = "query"),
        2: optional i32 max (api.source = "query"),
        3: optional string extra (api.source = "body"),
    }
    
    struct GetRandomResponse {
        1: optional i64 random_num,
    }
    
    // Service
    service RandomService {
       GetRandomResponse GetRandom (1: GetRandomRequest req) (api.get = "/api/get-random"),
    }

`api.source` 用来指定参数的位置，`query` 表示是 query 参数，`body` 表示 body 参数；`api.get="/api/get-random"` 表示接口路径是 /api/get-random，请求方法是 GET；

### 生成 Typescript ###

上面我们已经有了接口定义，那么对应的 Typescript 应该就呼之欲出了，一起来看代码：

interface GetRandomRequest {
        min: number;
        max: number;
        extra: string;
    }
    
    interface GetRandomResponse {
        random_num: number;
    }
    
    async function GetRandom(req: GetRandomRequest): Promise<GetRandomResponse> {
        return request<GetRandomResponse>({
            url: '/api/get-random',
            method: 'GET',
            query: {
                min: req.min,
                max: req.max,
            },
            body: {
                extra: req.extra,
            }
        });
    }

生成 Typescript 后，我们无需关心生成的代码长什么样，直接调用 `GetRandom` 即可。

### 架构设计 ###

要实现基于 thrift 生成代码，最核心的架构如下：

![format_png][]

因为 thrift 的内容我们不能直接拿来用，需要转化成中间代码（IR），这里的中间代码通常是 json、AST 或者自定义的 DSL。如果中间代码是 json，可能的结构如下：

{
        name: 'GetRandom',
        method: 'get',
        path: '/api/get-random',
        req_schema: {
            query_params: [
                {
                    name: 'min',
                    type: 'int',
                    optional: true,
                },
                {
                    name: 'max',
                    type: 'int',
                    optional: true,
                }
            ],
            body_params: [
                {
                    name: 'extra',
                    type: 'string',
                    optional: true,
                }
            ],
            header_params: [],
        },
        resp_schema: {
            header_params: [],
            body_params: [],
        } 
    }

为了保持架构的开放性，我们在核心链路上插入了 PrePlugin 和 PostPlugin，其中 PrePlugin 决定了 thrift 如何转化成 IR，PostPlugin 决定 IR 如何生成目标代码。

这里之所以是「目标代码」而不是「Typescript 代码」，是因为我希望不同的 PostPlugin 可以产生不同的目标代码，比如可以通过 TSPostPlugin 生成 Typescript 代码，通过 GoPostPlugin 生成 go 语言的代码。

### 总结 ###

代码生成这块的内容还有很多可以探索的地方，比如如何解析 thrift？是找第三方功能生成 AST 还是通过 pegjs 解析成自定义的 DSL？多文件联编如何处理、字段名 case 如何转换、运行时类型校验、生成的代码如何与 useRequest 或 ReactQuery 集成等。

thrift 其实可以看成接口定义的具体实现，如果 thrift 不满足你的业务场景，也可以自己实现一套类似的**接口定义**语言；接口定义作为前后端的约定，可以降低前后端的沟通成本；代码生成，可以提升前端代码的质量和研发效率。

如果本文对你有启发，欢迎点赞、关注、留言交流。

[format_png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/19dbc67cc32e49528b4c24f01e308aab.png