服务分组

概述

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

在 HTTP 服务开发中，随着业务的发展，我们的服务接口会越来越多，生成的代码文件(handler，logic，types 文件等)也会越来越多，这时候我们需要将一些生成的代码文件按照一定维度进行文件夹聚合，以便于开发和维护。

服务分组

假设我们有一个用户服务，我们有多个接口如下：

  1. https://example.com/v1/user/login
  2. https://example.com/v1/user/info
  3. https://example.com/v1/user/info/update
  4. https://example.com/v1/user/list
  6. https://example.com/v1/user/role/list
  7. https://example.com/v1/user/role/update
  8. https://example.com/v1/user/role/info
  9. https://example.com/v1/user/role/add
  10. https://example.com/v1/user/role/delete
  12. https://example.com/v1/user/class/list
  13. https://example.com/v1/user/class/update
  14. https://example.com/v1/user/class/info
  15. https://example.com/v1/user/class/add
  16. https://example.com/v1/user/class/delete

我们首先来看一下在不进行分组的情况下 api 语言的写法：

  1. syntax = "v1"
  3. type (
  4.     UserLoginReq{}
  5.     UserInfoReq{}
  6.     UserLoginResp{}
  7.     UserInfoResp{}
  8.     UserInfoUpdateReq{}
  9.     UserInfoUpdateResp{}
  10. )
  12. type (
  13.     UserRoleReq{}
  14.     UserRoleResp{}
  15.     UserRoleUpdateReq{}
  16.     UserRoleUpdateResp{}
  17.     UserRoleAddReq{}
  18.     UserRoleAddResp{}
  19.     UserRoleDeleteReq{}
  20.     UserRoleDeleteResp{}
  21. )
  23. type (
  24.     UserClassReq{}
  25.     UserClassResp{}
  26.     UserClassUpdateReq{}
  27.     UserClassUpdateResp{}
  28.     UserClassAddReq{}
  29.     UserClassAddResp{}
  30.     UserClassDeleteReq{}
  31.     UserClassDeleteResp{}
  32. )
  33. @server(
  34.     prefix: /v1
  35. )
  36. service user-api {
  37.     @handler UserLogin
  38.     post /user/login (UserLoginReq) returns (UserLoginResp)
  40.     @handler UserInfo
  41.     post /user/info (UserInfoReq) returns (UserInfoResp)
  43.     @handler UserInfoUpdate
  44.     post /user/info/update (UserInfoUpdateReq) returns (UserInfoUpdateResp)
  46.     @handler UserList
  47.     get /user/list returns ([]UserInfoResp)
  49.     @handler UserRoleList
  50.     get /user/role/list returns ([]UserRoleResp)
  52.     @handler UserRoleUpdate
  53.     get /user/role/update (UserRoleUpdateReq) returns (UserRoleUpdateResp)
  55.     @handler UserRoleInfo
  56.     get /user/role/info (UserRoleReq) returns (UserRoleResp)
  58.     @handler UserRoleAdd
  59.     get /user/role/add (UserRoleAddReq) returns (UserRoleAddResp)
  61.     @handler UserRoleDelete
  62.     get /user/role/delete (UserRoleDeleteReq) returns (UserRoleDeleteResp)
  64.     @handler UserClassList
  65.     get /user/class/list returns ([]UserClassResp)
  67.     @handler UserClassUpdate
  68.     get /user/class/update (UserClassUpdateReq) returns (UserClassUpdateResp)
  70.     @handler UserClassInfo
  71.     get /user/class/info (UserClassReq) returns (UserClassResp)
  73.     @handler UserClassAdd
  74.     get /user/class/add (UserClassAddReq) returns (UserClassAddResp)
  76.     @handler UserClassDelete
  77.     get /user/class/delete (UserClassDeleteReq) returns (UserClassDeleteResp)
  78. }

在不分组的情况下生成的代码目录结构如下：

  1. .
  2. ├── etc
  3. │   └── user-api.yaml
  4. ├── internal
  5. │   ├── config
  6. │   │   └── config.go
  7. │   ├── handler
  8. │   │   ├── routes.go
  9. │   │   ├── userclassaddhandler.go
  10. │   │   ├── userclassdeletehandler.go
  11. │   │   ├── userclassinfohandler.go
  12. │   │   ├── userclasslisthandler.go
  13. │   │   ├── userclassupdatehandler.go
  14. │   │   ├── userinfohandler.go
  15. │   │   ├── userinfoupdatehandler.go
  16. │   │   ├── userlisthandler.go
  17. │   │   ├── userloginhandler.go
  18. │   │   ├── userroleaddhandler.go
  19. │   │   ├── userroledeletehandler.go
  20. │   │   ├── userroleinfohandler.go
  21. │   │   ├── userrolelisthandler.go
  22. │   │   └── userroleupdatehandler.go
  23. │   ├── logic
  24. │   │   ├── userclassaddlogic.go
  25. │   │   ├── userclassdeletelogic.go
  26. │   │   ├── userclassinfologic.go
  27. │   │   ├── serclasslistlogic.go
  28. │   │   ├── userclassupdatelogic.go
  29. │   │   ├── userinfologic.go
  30. │   │   ├── userinfoupdatelogic.go
  31. │   │   ├── userlistlogic.go
  32. │   │   ├── userloginlogic.go
  33. │   │   ├── userroleaddlogic.go
  34. │   │   ├── userroledeletelogic.go
  35. │   │   ├── userroleinfologic.go
  36. │   │   ├── userrolelistlogic.go
  37. │   │   └── userroleupdatelogic.go
  38. │   ├── svc
  39. │   │   └── servicecontext.go
  40. │   └── types
  41. │       └── types.go
  42. ├── user.api
  43. └── user.go
  45. 7 directories, 35 files

由于我们没有进行分组，所以生成的代码中handler 和 logic 结构体目录下的文件是全部揉在一起的，这样的目录结构在项目中不太好管理和阅读，接下来我们按照 user，role，class 来进行分组，在 api 语言中，我们可以通过在 @server 语句块中使用 group 关键字来进行分组，分组的语法如下：

  1. syntax = "v1"
  3. type (
  4.     UserLoginReq  {}
  5.     UserInfoReq  {}
  6.     UserLoginResp  {}
  7.     UserInfoResp  {}
  8.     UserInfoUpdateReq  {}
  9.     UserInfoUpdateResp  {}
  10. )
  12. type (
  13.     UserRoleReq  {}
  14.     UserRoleResp  {}
  15.     UserRoleUpdateReq  {}
  16.     UserRoleUpdateResp  {}
  17.     UserRoleAddReq  {}
  18.     UserRoleAddResp  {}
  19.     UserRoleDeleteReq  {}
  20.     UserRoleDeleteResp  {}
  21. )
  23. type (
  24.     UserClassReq  {}
  25.     UserClassResp  {}
  26.     UserClassUpdateReq  {}
  27.     UserClassUpdateResp  {}
  28.     UserClassAddReq  {}
  29.     UserClassAddResp  {}
  30.     UserClassDeleteReq  {}
  31.     UserClassDeleteResp  {}
  32. )
  34. @server (
  35.     prefix: /v1
  36.     group:  user
  37. )
  38. service user-api {
  39.     @handler UserLogin
  40.     post /user/login (UserLoginReq) returns (UserLoginResp)
  42.     @handler UserInfo
  43.     post /user/info (UserInfoReq) returns (UserInfoResp)
  45.     @handler UserInfoUpdate
  46.     post /user/info/update (UserInfoUpdateReq) returns (UserInfoUpdateResp)
  48.     @handler UserList
  49.     get /user/list returns ([]UserInfoResp)
  50. }
  52. @server (
  53.     prefix: /v1
  54.     group:  role
  55. )
  56. service user-api {
  57.     @handler UserRoleList
  58.     get /user/role/list returns ([]UserRoleResp)
  60.     @handler UserRoleUpdate
  61.     get /user/role/update (UserRoleUpdateReq) returns (UserRoleUpdateResp)
  63.     @handler UserRoleInfo
  64.     get /user/role/info (UserRoleReq) returns (UserRoleResp)
  66.     @handler UserRoleAdd
  67.     get /user/role/add (UserRoleAddReq) returns (UserRoleAddResp)
  69.     @handler UserRoleDelete
  70.     get /user/role/delete (UserRoleDeleteReq) returns (UserRoleDeleteResp)
  71. }
  73. @server (
  74.     prefix: /v1
  75.     group:  class
  76. )
  77. service user-api {
  78.     @handler UserClassList
  79.     get /user/class/list returns ([]UserClassResp)
  81.     @handler UserClassUpdate
  82.     get /user/class/update (UserClassUpdateReq) returns (UserClassUpdateResp)
  84.     @handler UserClassInfo
  85.     get /user/class/info (UserClassReq) returns (UserClassResp)
  87.     @handler UserClassAdd
  88.     get /user/class/add (UserClassAddReq) returns (UserClassAddResp)
  90.     @handler UserClassDelete
  91.     get /user/class/delete (UserClassDeleteReq) returns (UserClassDeleteResp)
  92. }

我们再来看一下分组后的代码生成目录结构：

  1. .
  2. ├── etc
  3. │   └── user-api.yaml
  4. ├── internal
  5. │   ├── config
  6. │   │   └── config.go
  7. │   ├── handler
  8. │   │   ├── class
  9. │   │   │   ├── userclassaddhandler.go
  10. │   │   │   ├── userclassdeletehandler.go
  11. │   │   │   ├── userclassinfohandler.go
  12. │   │   │   ├── userclasslisthandler.go
  13. │   │   │   └── userclassupdatehandler.go
  14. │   │   ├── role
  15. │   │   │   ├── userroleaddhandler.go
  16. │   │   │   ├── userroledeletehandler.go
  17. │   │   │   ├── userroleinfohandler.go
  18. │   │   │   ├── userrolelisthandler.go
  19. │   │   │   └── userroleupdatehandler.go
  20. │   │   ├── routes.go
  21. │   │   └── user
  22. │   │       ├── userinfohandler.go
  23. │   │       ├── userinfoupdatehandler.go
  24. │   │       ├── userlisthandler.go
  25. │   │       └── userloginhandler.go
  26. │   ├── logic
  27. │   │   ├── class
  28. │   │   │   ├── userclassaddlogic.go
  29. │   │   │   ├── userclassdeletelogic.go
  30. │   │   │   ├── userclassinfologic.go
  31. │   │   │   ├── userclasslistlogic.go
  32. │   │   │   └── userclassupdatelogic.go
  33. │   │   ├── role
  34. │   │   │   ├── userroleaddlogic.go
  35. │   │   │   ├── userroledeletelogic.go
  36. │   │   │   ├── userroleinfologic.go
  37. │   │   │   ├── userrolelistlogic.go
  38. │   │   │   └── userroleupdatelogic.go
  39. │   │   └── user
  40. │   │       ├── userinfologic.go
  41. │   │       ├── userinfoupdatelogic.go
  42. │   │       ├── userlistlogic.go
  43. │   │       └── userloginlogic.go
  44. │   ├── svc
  45. │   │   └── servicecontext.go
  46. │   └── types
  47. │       ├── class.go
  48. │       ├── role.go
  49. │       └── user.go
  50. └── user.go
  52. 14 directories, 36 files

通过分组，我们可以很方便的将不同的业务逻辑分组到不同的目录下，这样可以很方便的管理不同的业务逻辑。

服务分组 - 图1注意

通过命令行参数 --types-group 可开启 types 分组，types 分组会按照 group 名称生成不同的文件，而不是按照目录分组，生成示例如下

  1. goctl api go --api $api --dir $output --type-group

types 分组需要 goctl 大于等于 1.8.3 版本 该功能处于实验性阶段，如果兼容问题请执行命令 goctl env -w GOCTL_EXPERIMENTAL=off 关闭实验性功能即可 请注意，实验功能非稳定版本，有存在调整的可能。