文本消息发送：构造请求体、API 调用流程及 Go 语言的 Struct 映射实现

主动发送外部群消息的核心是正确构造 HTTP 请求体，并将其发送到正确的企业微信 API 接口。我们将重点关注最基础的文本消息类型。

1. API 接口与请求结构

用于发送应用消息给客户群的接口是：

\\text{POST } /cgi\\text{-}bin/appchat/send\\text{?access\\_token=ACCESS\\_TOKEN}

请求体格式： JSON
必需参数： chatid（群聊 ID）和 msgtype（消息类型）。

文本消息 (Text Message) 的 JSON 请求体

发送文本消息时，msgtype 必须设置为 "text"，并在 text 字段中嵌套 content 字段。

复制代码

{
   "chatid": "CHAT_ID_XYZ",
   "msgtype": "text",
   "text": {
        "content": "这是您发送的文本内容，请保持简洁和重点突出。"
   }
}

2. Go 语言的 Struct 映射实现

在 Go 语言中，最佳实践是使用 Struct 来定义请求和响应的数据结构，并利用标准库 encoding/json 进行 JSON 序列化（Marshal）和反序列化（Unmarshal）。

2.1 请求 Struct 定义

为了清晰地表示 JSON 结构，我们定义嵌套 Struct：

Go 复制代码

// 消息主体 Struct，用于嵌套文本内容
type TextContent struct {
    Content string `json:"content"`
}

// 完整的文本消息请求 Struct
type SendTextMessageRequest struct {
    ChatID  string      `json:"chatid"`
    MsgType string      `json:"msgtype"`
    Text    TextContent `json:"text"`
}

json:"..." Tag： Go 字段名使用大驼峰（ChatID），而 JSON 字段名使用小写（chatid）。通过 Struct Tag 实现两者之间的精确映射。

2.2 构造和序列化请求体 (Marshaling)

在发送前，需要将 Go Struct 转换为 JSON 字节流。

Go 复制代码

import "encoding/json"

func createTextRequest(chatID string, content string) ([]byte, error) {
    // 实例化 Struct
    request := SendTextMessageRequest{
        ChatID:  chatID,
        MsgType: "text",
        Text: TextContent{
            Content: content,
        },
    }

    // 转换为 JSON 字节流
    payload, err := json.Marshal(request)
    if err != nil {
        return nil, err
    }
    return payload, nil
}

3. API 调用流程与响应处理

客户端将序列化后的 JSON Payload 通过 HTTP POST 发送到企业微信接口。

3.1 响应 Struct 定义

企业微信的 API 响应通常包含错误码和错误信息。

Go 复制代码

// 所有 API 响应的基础结构
type BaseResponse struct {
    ErrCode int    `json:"errcode"`
    ErrMsg  string `json:"errmsg"`
}

// 文本消息发送的响应，通常只返回 BaseResponse
type SendMessageResponse struct {
    BaseResponse
    // 其他如 msgid, invalidparty 等字段（群发接口可能包含）
}

3.2 错误处理

在接收到 HTTP 响应后，必须检查两层错误：

HTTP 状态码： 检查 HTTP 状态码是否为 $200$ 。非 $200$ 通常表示网络或服务器故障。
API 错误码： 检查 JSON 响应中的 errcode 字段。只有 errcode 为 $0$ 时，消息才发送成功。非 $0$ 时，根据具体的错误码执行重试或告警逻辑（例如 $40014$ 触发 Token 刷新）。

通过 Go Struct 映射，我们实现了清晰、类型安全且易于维护的 API 客户端代码。

QiWe开放平台提供了后台直登功能，登录成功后获取相关参数，快速Apifox在线测试，所有登录功能都是基于QiWe平台API自定义开发。