使用Go-Chassis框架开发REST服务的完整指南

使用Go-Chassis框架开发REST服务的完整指南

概述

Go-Chassis是一个微服务框架，它提供了构建分布式系统的核心能力。本文将详细介绍如何使用Go-Chassis框架开发REST风格的微服务，包括服务提供者和消费者的实现。

服务提供者开发

项目结构

建议采用以下目录结构组织REST服务代码：

server
├── main.go
└── conf
    ├── chassis.yaml
    └── microservice.yaml

核心代码实现

1. 定义服务结构体

首先创建一个结构体来封装HTTP处理逻辑：

type RestFulHello struct {}

func (r *RestFulHello) SayHello(b *rf.Context) {
    b.Write([]byte("get user id: " + b.ReadPathParameter("userid")))
}

2. 定义路由规则

实现URLPatterns()方法定义API路由：

func (r *RestFulHello) URLPatterns() []rf.Route {
    return []rf.RouteSpec{
        {
            Method: http.MethodGet, 
            Path: "/sayhello/{userid}", 
            ResourceFunc: r.SayHello,
            Returns: []*rf.Returns{{Code: 200}}
        },
    }
}

配置文件

1. chassis.yaml配置

servicecomb:
  registry:
      address: http://127.0.0.1:30100 
  protocols:
    rest: # 启动HTTP服务器
      listenAddress: 127.0.0.1:5001

2. microservice.yaml配置

servicecomb:
  service:
    name: RESTServer # 服务名称

服务注册与启动

在main.go中完成服务注册和启动：

func main() {
    // 注册服务结构体
    chassis.RegisterSchema("rest", &RestFulHello{})
    
    // 初始化框架
    if err := chassis.Init(); err != nil {
        openlog.Error("Init failed. "+err.Error())
        return
    }
    
    // 启动服务
    chassis.Run()
}

服务消费者开发

项目结构

消费者项目建议采用以下结构：

client
├── main.go
└── conf
    ├── chassis.yaml
    └── microservice.yaml

配置文件

1. chassis.yaml配置

servicecomb:
  registry:
      address: http://127.0.0.1:30100

2. microservice.yaml配置

servicecomb:
  service:
    name: RESTClient # 消费者名称

服务调用实现

func main() {
    // 初始化框架
    if err := chassis.Init(); err != nil {
        openlog.Error("Init failed." + err.Error())
        return
    }
    
    // 创建请求
    req, err := rest.NewRequest("GET", "http://RESTServer/sayhello/world", nil)
    if err != nil {
        openlog.Error("new request failed.")
        return
    }
    
    // 执行调用
    resp, err := core.NewRestInvoker().ContextDo(context.TODO(), req)
    if err != nil {
        openlog.Error("do request failed.")
        return
    }
    defer resp.Body.Close()
    
    // 处理响应
    openlog.Info("REST Server sayhello[GET]: " + string(httputil.ReadBody(resp)))
}

高级路由配置

在URLPatterns中可以定义更复杂的路由规则：

func (d *Data) URLPatterns() []rf.Route {
    return []rf.Route{
        {
            Method: http.MethodGet,
            Path: "/price/{id}",
            ResourceFunc: d.GetPrice,
            Consumes: []string{goRestful.MIME_JSON, goRestful.MIME_XML},
            Produces: []string{goRestful.MIME_JSON},
            Returns: []*rf.Returns{
                {Code: http.StatusOK, Message: "true", Model: Data{}}
            },
            Parameters: []*rf.Parameters{
                {"x-auth-token", "string", goRestful.HeaderParameterKind, "this is a token"},
                {"x-auth-token2", "string", goRestful.HeaderParameterKind, "this is a token"},
            },
        },
    }
}

参数类型说明

Go-Chassis支持多种参数类型：

PathParameterKind    // 路径参数
QueryParameterKind   // 查询参数
BodyParameterKind    // 请求体参数
HeaderParameterKind  // 请求头参数
FormParameterKind    // 表单参数

API文档自动生成

服务启动后，可以通过以下URL获取OpenAPI文档：

http://ip:port/apidocs.json

可以将返回的JSON内容复制到Swagger Editor中查看完整的API文档。

配置注意事项

1. 禁用自动生成Schema

如需自定义Schema而非自动生成，可在chassis.yaml中添加：

servicecomb:
  noRefreshSchema: true

2. 配置文件路径

如果conf目录不在工作目录下，需要设置环境变量：

export CHASSIS_HOME=/path/to/conf/parent_folder
# 或
export CHASSIS_CONF_DIR=/path/to/conf_folder

最佳实践

1. 所有公开的方法必须以大写字母开头
2. 处理方法必须使用*restful.Context作为唯一输入参数
3. 必须实现URLPatterns()方法定义路由
4. 建议为每个API定义完整的返回码和模型
5. 合理使用参数类型，特别是Header参数常用于认证场景

通过以上步骤，您可以快速构建基于Go-Chassis的RESTful微服务，并实现服务间的调用。框架提供的自动API文档生成功能也能大大提升开发效率。