HTTP methodBody 源契约

HTTP 方法的 methodBody 是项目源码的一部分。所有可修改源码的生产者，包括 Manager、 代码生成器、项目模板、迁移脚本和其他自动化工具，都必须直接写入本页定义的 snake_case 字段。

这个要求只作用于 HTTP methodBody。module.json 和方法定义外层的 paramDefinitions、 returnType、errorTypeMap 等字段仍服从各自现行协议，不能做全文件机械重命名。

方法类型与 HTTP 动词

HTTP 模块方法文件外层的 type 表示平台方法实现类型，编译后对应运行时方法的 @type。 当前 HTTP 方法的合法值是 HttpMethod；它不是 HTTP 请求动词。

GET、POST 等 HTTP 动词必须写入 methodBody.http_method，查询参数必须写入 methodBody.query。GET、POST 和 QUERY 都不能写入方法实现类型。准确层级是：

type = HttpMethod
└── methodBody.http_method = GET | POST | ...
└── methodBody.query = 查询参数映射

创建一个 GET 查询方法时，方法文件中的 methodBody 可以写为：

{
  "request_url": "{serviceBaseUrl}/api/items",
  "protocol": "http",
  "http_method": "GET",
  "url": {
    "serviceBaseUrl": {
      "required": true,
      "position": "property",
      "key": "serviceBaseUrl"
    }
  },
  "body": null,
  "query": {
    "PageIndex": {
      "required": false,
      "position": "params",
      "key": "pageIndex"
    }
  },
  "header": {},
  "body_format": "json",
  "return_format": "json"
}

方法通过项目 Git 源码维护，再由 baijimu bundle module version create --help 当前命令面从精确 Git 提交创建不可变模块版本。不要使用历史 baijimu module method create 命令或旧的离线能力快照； 它们不是当前模块源码写入入口。

规范字段

methodBody 顶层只允许以下字段：

url、body、query 和 header 决定解析后的值写入 HTTP 请求的目标位置。每个映射项可包含 required、position、key、default 和 expression；映射对象的键是目标字段名，key 是 对应来源中的字段名。目标位置与值来源是两个不同维度，不能把外层映射名重复写进 position。

公开参数来源

模块项目源码允许写入的 position 只有以下四种：

普通公共参数可以省略 position，省略时按 params 处理；生成器、模板和迁移脚本应显式写 position: "params"，避免来源含糊。使用 expression 计算值时可以省略 position，表达式中只能引用 当前公开上下文支持的变量。除上表四个值之外的来源由平台内部物化流程拥有，不属于模块项目作者协议， 不得由项目源码、Manager、模板或生成器写入。

例如，item_id 是后端 URL 占位符，而它的值来自公共方法参数 itemId；name 和 pageNumber 也来自公共方法参数：

{
  "request_url": "https://api.example.com/v1/items/{item_id}",
  "protocol": "http",
  "http_method": "POST",
  "url": {
    "item_id": {
      "required": true,
      "position": "params",
      "key": "itemId"
    }
  },
  "body": {
    "name": {
      "required": true,
      "position": "params",
      "key": "name"
    }
  },
  "query": {
    "page": {
      "required": false,
      "position": "params",
      "key": "pageNumber"
    }
  },
  "header": {},
  "body_format": "json",
  "return_format": "json",
  "backend_response_format": "cmodel",
  "error_code_field": "code",
  "error_message_field": "message",
  "data_field": "data",
  "success_expression": "response.code == 0",
  "error_code_expression": "response.code",
  "error_message_expression": "response.message",
  "data_expression": "response.data"
}

以下写法是错误的，因为它把 HTTP 目标位置误写成了值来源，模块版本创建会拒绝：

{
  "url": {
    "item_id": {
      "position": "url"
    }
  },
  "body": {
    "name": {
      "position": "body"
    }
  },
  "query": {
    "page": {
      "position": "query"
    }
  }
}

项目服务能够读取对象形式或历史项目中的 JSON 字符串形式；修改时保留当前方法文件的 外层存储形状，但字符串内部也必须使用上述 snake_case 字段。

历史兼容边界

历史 httpMethod、bodyFormat、returnFormat、backendResponseFormat、 errorCodeField、errorMessageField、dataField 以及各类 *Expression 驼峰字段，只能 在受控输入边界读取并转换。它们不是新的写入协议，任何生产者都不能继续产生这些字段。

如果同一语义同时出现 snake_case 和历史字段，保存方必须拒绝冲突，不能猜测哪一个正确。 未知顶层字段也会在模块版本创建时被拒绝，不能静默丢弃。读取旧项目后只要发生保存，就应 输出单一的规范字段集合。

历史项目还可能把外层 url、body、query 或 header 名称写入映射项的 position。迁移时 不能按外层位置机械替换：先确认值的权威来源；来自公共方法参数时改为 params，来自 Runtime 上下文时 改为 context，来自模块属性时改为 property，非敏感协议常量才改为 fixed 并提供 default。 无法确认来源时必须停止迁移并检查 paramDefinitions、模块属性和调用上下文，不能猜测或增加兜底。

当前 baijimu bundle manifest validate 只校验 Bundle 项目清单，不校验模块项目中的 module.json 和 methods/*.json。创建模块版本前仍须按本页检查源码；最终由模块版本创建接口使用 当前平台合同执行严格校验。公开模块方法 JSON Schema 或对应 CLI 离线校验命令发布后，应以其版本化 合同为准，不能自行复制平台内部类型生成另一份枚举。

修改检查

提交前至少检查：

1. 只修改预期的 methods/*.json，没有机械重命名方法定义外层字段。
2. methodBody 不包含带大写字母的顶层字段，也不同时包含历史别名。
3. request_url 非空；使用 params 时，映射项的 key 能在 paramDefinitions 中找到对应公共参数。
4. position 只使用 params、context、property 或 fixed，没有写入 url、body、query、header 或内部来源。
5. 生成器、模板和 UI 保存结果与手写项目文件使用同一规范。
6. 创建模块版本后，安装 Artifact 中仍只出现 snake_case 字段。

完成源码修改后，按模块冻结与 Bundle 交付 提交项目 Git、创建模块版本并纳入 Bundle。