![截屏2026-05-26 00.30.21.png](https://developer.qcloudimg.com/http-save/yehe-6954299/15bc690fea0ed8db8a287ee50f1f29b3.png)

傳統api調用存在很多問題。

1. 很多應用，api是沒有文檔的，調用者根本無法得知api的請求參數和返回數據是什麼樣的，規範是什麼。
2. 發佈一個api，可能還得發佈文檔，比如Swagger。大多數開發者很難寫好文檔，文檔質量參差不齊。
3. 文檔發佈地址就是一個問題。即使有文檔，也很難找。還有一些文檔受限於網絡、權限等，看不了。
4. 文檔可能和api脫節，更新不及時。甚至造成各種歧義。
5. 文檔很難管理，丟失、遺忘等問題很常見。
6. 開發者、調用者之間協作困難，甚至相互誤解。
...

問題太多了，這只是冰山一角。而MetaMessage的出現，可能真正改變了這種局面。

MetaMessage，自描述、自規範、自示例。比如，輸出為一個文本格式jsonc：

```jsonc
{
  // mm: type=datetime; desc=創建時間
  "create_time": "2026-01-01 00:00:00",
}
```

看起來很簡單，type表示了數據格式，各種語言實現一致，不會出現某個語言解釋為字符串的問題。desc可以描述字段含義、使用方法等。
當然還有更多標籤，這些標籤共同描述了一種精確、完整的數據。

開發者可以直接從各語言的數據對象直接生成mm，也可以通過比如jsonc字符串生成mm。代表的數據是完全一致的。
說到這裡，對於多語言間的數據對比，實際很困難，甚至說還沒有一個好的方法真正能做到，對於測試來說就是一個很大的問題。
而都轉成mm，對比文本非常方便。

還有一些其他的優點，比如可以生成緊湊的二進制，可以生成更多文本格式等等。未來，一個mm可以生成jsonc、toml、yaml等格式，作為配置文件的轉換非常方便。

遠了。

我們在調用一個api的時候，能不能直接獲取它的請求方法？我想到一個方法，我們可以利用resful的options方法。options方法設計之初就是資源探測，但是幾十年來，大家僅僅是用來表示cors，描述跨域問題。太浪費了。而且瀏覽器默認會在post等請求前，調用下options方法，我們是沒辦法取消的，有點可笑了。我們可以把請求參數方法放在options返回的body中，這樣調用方不就能獲得實時的、準確的請求方法了嗎？

```jsonc
OPTIONS /api/v1/users/1:

// mm: example
{

        // mm: nullable; desc="用戶名稱"
        "name": "",

        // mm: type=email; nullable; desc="電子郵箱"
        "email": "",

        // mm: type=u8; nullable; desc="年齡"
        "age": 0,

        // mm: nullable; desc="是否激活"
        "is_active": false,
}
```

這時一個修改用戶的api，當我們看到這個結果，我們就能知道`name`可以為null，`age`必須是uint8.當然整體上還能得出這是個`example`示例數據。

我們請求的時候，只要完全符合，那麼就是安全合法的。

## 實踐

我們來做一個golang gin的中間件，實現這樣的功能：

1. 對於post、put、patch方法，把請求參數自動包裝、暴露到options
2. 自動以mm對請求進行編碼
3. 對返回結果自動解嗎

為了方便使用和演示，我們還可以做個客戶端：

1. 請求的時候，自動探測schema，也就是請求options
2. 自動驗證請求合法性

當然服務端和客戶端都會自動驗證。

server:
```golang
...

type CreateUserRequest struct {
    Name  string `mm:"desc=用戶名稱; min=1; max=50"`
    Email string `mm:"type=email; desc=電子郵箱"`
    Age   uint8  `mm:"desc=年齡; min=0; max=150"`
}

mmgin.POST("/users", createUser)

func createUser(c *gin.Context, req *CreateUserRequest) {
    newUser := User{
        ID:       int64(len(users) + 1),
        Name:     req.Name,
        Email:    req.Email,
        Age:      req.Age,
        IsActive: true,
    }
    users = append(users, newUser)

    mmgin.RespondWithStatus(c, http.StatusCreated, APIResponse{
        Code:    0,
        Message: "user created",
        Data:    &newUser,
    }, "")
}
...
```

client:
```golang
...

type CreateUserRequest2 struct {
    Name  string `mm:"desc=用戶名稱; min=1; max=50"`
    Email string `mm:"type=email; desc=電子郵箱"`
    Age   uint8  `mm:"desc=年齡; min=0; max=150"`
}

createReq := &CreateUserRequest2{
    Name:  "David",
    Email: "david@example.com",
    Age:   28,
}
resp3, err := client.POST[CreateUserRequest2, APIResponse]("/api/v1/users", createReq)
if err != nil {
    fmt.Printf("  [Error] %v\n", err)
    return
}
fmt.Printf("  [OK] Message: %s\n", resp3.Message)
fmt.Printf("     New User: %+v\n", resp3.Data)
...
```

以上可以看到，使用非常簡單，甚至無感。
完整示例可參見"metamessage/mm-gin"項目

可測試的結果是，只要請求數據不合法，在options階段就會失敗。

注意這是強一致的，是實時驗證的。

## 未來

api不用寫文檔，代碼就是文檔。

每個api接口，自動生成一個schema

陌生的api，沒關係，自動獲取請求參數；api更新，沒關係，自動獲得更新後的請求參數。

特別是眾多瀏覽器，怎麼也不會想到options還能這麼用，如果內置這種用法，對各種api更是幫助巨大。

MetaMessage作為基礎協議，會在各種場景有更多重要應用。

很多應用，api是沒有文檔的，調用者根本無法得知api的請求參數和返回數據是什麼樣的，規範是什麼。

MetaMessage，開啟了API革命！

后端

架构设计

开发工具

传统API文档存在更新滞后、管理困难等问题。MetaMessage通过自描述数据结构实现API参数自动验证，利用OPTIONS方法实时获取请求规范。开发者无需编写文档，代码即文档，支持多语言数据一致性对比。该方案简化API调用流程，提升开发效率，确保请求合法性验证在options阶段即可完成。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

MetaMessage，開啟了API革命！-腾讯云开发者社区-腾讯云

MetaMessage，開啟了API革命！

MetaMessage，開啟了API革命！

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐