API Import

概述

在 go-zero 中，我们通过 api 语言来声明 HTTP 服务，然后通过 goctl 生成 HTTP 服务代码，在之前我们系统性的介绍了 API 规范。

在 HTTP 服务开发中，我们都是通过 api 描述语言来描述 HTTP 服务，随着业务量的增加，api 文件可能会越来越大，又或者我们有一些公共结构体，如果我们都写在同一个 api 文件中，那么 api文件将变成非常巨大，不易阅读和维护，我们可以通过 api import 来引入其他 api 文件解决这类问题。

api 文件引入

假设我们 HTTP 服务的响应格式统一为如下 json 格式：

  1. {
  2. "code": 0,
  3. "msg": "success",
  4. "data": {}
  5. }

通过如上 json 可以看出，我们的响应格式中有 code、msg、data 三个字段，其中 code 和 msg 是固定的，data 是可变的，我们可以将其中2个字段 code，msg 抽象出来，定义为一个公共的结构体，然后在其他 api 文件中引入这个结构体。

示例，假设我们有一个用户服务来查询用户信息和修改用户信息，我们可以将 code 和 msg 抽象在 base.api 中，然后 user.api 中复用和定义具体的响应结构体即可。

  • base.api
  • user.api
  1. syntax =  "v1"
  3. type Base {
  4.     Code int    `json:"code"`
  5.     Msg  string `json:"msg"`
  6. }
  1. syntax = "v1"
  3. // 引入 base.api 文件
  4. import "base.api"
  6. type UserInfoReq {
  7.     Id int64 `path:"id"`
  8. }
  10. type UserInfo {
  11.     Id   int64  `path:"id"`
  12.     Name string `json:"name"`
  13.     Age  int    `json:"age"`
  14. }
  16. type UserInfoResp {
  17.     Base // Base 为 base.api 中的公共结构体，在 api 描述语言中，没有 package 的概念
  18.     Data UserInfo `json:"data"`
  19. }
  21. type UserInfoUpdateReq {
  22.     Id int64 `json:"id"`
  23.     UserInfo
  24. }
  26. type UserInfoUpdateResp {
  27.     Base
  28. }
  30. service user {
  31.     @handler userInfo
  32.     get /user/info/:id (UserInfoReq) returns (UserInfoResp)
  34.     @handler userInfoUpdate
  35.     post /user/info/update (UserInfoUpdateReq) returns (UserInfoUpdateResp)
  36. }
API Import - 图1温馨提示

在 api 描述语言中，没有 package 的概念，所以在引入其他 api 文件时，需要使用相对路径，如上面示例中的 import "base.api"，如果是在同一个目录下，亦可以使用 import "./base.api"。 import 支持相对路径和绝对路径。

在 api 描述语言中，我们规定将所有 service 语法块声明的 HTTP 服务信息都放在 main api文件中，抽象结构体放在其他 api 文件中，然后在 main api 文件中引入其他 api 文件，这样可以让 main api 文件更加简洁，易于维护，而被引入的 api 文件中不允许出现 service 语法块，否则会报错。

特别注意：api 引入不支持循环引入！！！