本章节我们将使用固定的数据格式返回结果,无论路由函数执行成功还是失败,我们以json格式返回结果给调用端。

返回格式定义

我们定义一个统一的数据结构:

  1. type Response struct {
  2. Message string `json:"message" dc:"消息提示"`
  3. Data interface{} `json:"data" dc:"执行结果"`
  4. }

由于我们需要返回json数据格式,因此我们给每个字段都加上json标签。

接口数据结构

  1. type HelloReq struct {
  2. g.Meta `path:"/" method:"get"`
  3. Name string `v:"required" json:"name" dc:"姓名"`
  4. Age int `v:"required" json:"age" dc:"年龄"`
  5. }
  6. type HelloRes struct {
  7. Content string `json:"content" dc:"返回结果"`
  8. }
  • 我们给HelloRes增加了一个Content属性,用于路由函数返回具体的数据。
  • 由于需要通过json数据格式返回数据,因此所有的属性字段均增加json标签。

路由回调函数

  1. type Hello struct{}
  2. func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) {
  3. res = &HelloRes{
  4. Content: fmt.Sprintf(
  5. "Hello %s! Your Age is %d",
  6. req.Name,
  7. req.Age,
  8. ),
  9. }
  10. return
  11. }

我们这里通过HelloRes返回数据结构返回执行结果,而不是像前面的示例那样通过g.RequestFromCtx(ctx)获取原始的请求对象直接Write结果。

中间件定义

  1. func Middleware(r *ghttp.Request) {
  2. r.Middleware.Next()
  3. var (
  4. msg string
  5. res = r.GetHandlerResponse()
  6. err = r.GetError()
  7. )
  8. if err != nil {
  9. msg = err.Error()
  10. } else {
  11. msg = "OK"
  12. }
  13. r.Response.WriteJson(Response{
  14. Message: msg,
  15. Data: res,
  16. })
  17. }

在该中间件中:

  • 通过r.GetHandlerResponse()方法获取路由回调函数的执行结果,即路由回调函数返回的第一个结果参数*HelloRes
  • 通过r.GetError()获取路由回调函数的执行状态,即路由回调函数返回的第二个结果参数error,如果该结果不为nil,表示该回调函数执行产生了错误。
  • 通过r.Response.WriteJson将结果整合到统一的返回数据结构Response,并编码为json格式返回给调用端。

完整示例代码

main.go

  1. package main
  2. import (
  3. "context"
  4. "fmt"
  5. "github.com/gogf/gf/v2/frame/g"
  6. "github.com/gogf/gf/v2/net/ghttp"
  7. )
  8. type Response struct {
  9. Message string `json:"message" dc:"消息提示"`
  10. Data interface{} `json:"data" dc:"执行结果"`
  11. }
  12. type HelloReq struct {
  13. g.Meta `path:"/" method:"get"`
  14. Name string `v:"required" json:"name" dc:"姓名"`
  15. Age int `v:"required" json:"age" dc:"年龄"`
  16. }
  17. type HelloRes struct {
  18. Content string `json:"content" dc:"返回结果"`
  19. }
  20. type Hello struct{}
  21. func (Hello) Say(ctx context.Context, req *HelloReq) (res *HelloRes, err error) {
  22. res = &HelloRes{
  23. Content: fmt.Sprintf(
  24. "Hello %s! Your Age is %d",
  25. req.Name,
  26. req.Age,
  27. ),
  28. }
  29. return
  30. }
  31. func Middleware(r *ghttp.Request) {
  32. r.Middleware.Next()
  33. var (
  34. msg string
  35. res = r.GetHandlerResponse()
  36. err = r.GetError()
  37. )
  38. if err != nil {
  39. msg = err.Error()
  40. } else {
  41. msg = "OK"
  42. }
  43. r.Response.WriteJson(Response{
  44. Message: msg,
  45. Data: res,
  46. })
  47. }
  48. func main() {
  49. s := g.Server()
  50. s.Group("/", func(group *ghttp.RouterGroup) {
  51. group.Middleware(Middleware)
  52. group.Bind(
  53. new(Hello),
  54. )
  55. })
  56. s.SetPort(8000)
  57. s.Run()
  58. }

该示例中的所有代码我们已经做过了介绍,我们直接执行即可。

执行结果

运行后,我们访问 http://127.0.0.1:8000/?name=john&age=18 可以看到,页面输出结果符合预期。

img_3.png

我们尝试一下错误的参数请求 http://127.0.0.1:8000/ 可以看到,页面输出结果也同样符合预期。

img_5.png

学习小结

在本章节中,我们学会了使用常用的json格式对接口进行统一的数据格式封装,这在有着成百上千接口的业务项目中是非常有必要的。

可以看到,我们已经将参数完整地进行了结构化,结构中带有详细的输入输出参数描述、类型定义甚至数据校验规则, 那么我们能否基于这些信息自动化地生成接口文档呢?答案也是肯定的,我们将在下一章节介绍。