Skip to content

更新小程序 ​

1. 接口定位 ​

  • 接口名称: 更新小程序
  • 所属域: admin/applet
  • 业务目标: 按小程序 ID 局部更新已存在的小程序配置

2. 请求定义 ​

  • Method: POST
  • Path: /applet/update
  • Content-Type: 推荐 application/json
  • operationID: 必填,请通过 Header operationID 传入
  • 鉴权: 需要 Header token,且必须是管理员 token
  • 幂等性: 对相同更新内容重复提交可视为幂等

3. 请求参数 ​

Header 参数 ​

字段必填类型说明
operationID是string链路追踪 ID
token是string管理员 token

Body 参数 ​

字段必填类型说明
id是string要更新的小程序 ID
name否objectwrapper 字段,存在时更新名称
appID否objectwrapper 字段,存在时更新业务 AppID
icon否objectwrapper 字段,存在时更新图标
url否objectwrapper 字段,存在时更新访问地址
md5否objectwrapper 字段,存在时更新摘要
size否objectwrapper 字段,存在时更新安装包大小
version否objectwrapper 字段,存在时更新版本号
priority否objectwrapper 字段,存在时更新排序优先级
status否objectwrapper 字段,存在时更新状态
createTime否object请求结构中存在,但当前更新逻辑不会处理该字段

wrapper 字段说明 ​

  • StringValue 风格字段使用:{ "value": "new-value" }
  • Int64Value 风格字段使用:{ "value": 123 }
  • UInt32Value 风格字段使用:{ "value": 1 }

字段约束 ​

  • 协议校验要求 id 不能为空。
  • 服务端会先确认目标小程序存在。
  • 更新字段必须至少传一个,否则返回 no update info。
  • 局部更新转换规则:
    • name/appID/url/version 传空字符串会报错
    • md5 传入时会校验是否是长度正确的十六进制 MD5
    • size 传入时必须大于 0
    • status 传入时当前实现不会再次校验是否只能为 1/2

4. 响应结构 ​

通用响应包裹 ​

字段类型说明
errCodeint错误码,0 表示成功
errMsgstring错误简述
errDltstring错误详情
dataobject业务数据

data 字段 ​

  • 本接口成功时返回空对象(无业务字段)。

5. 业务规则 ​

  • 仅管理员可以调用。
  • 更新流程是“先查存在性,再转更新字典,再执行 $set 更新”。
  • 只有请求中显式传入的 wrapper 字段才会被更新;未传字段保持原值。

6. 错误码与失败场景 ​

错误码场景典型报错
1001id 为空id is empty
1001没有任何可更新字段no update info
1001name 传空字符串name is empty
1001appID 传空字符串appID is empty
1001url 传空字符串url is empty
1001md5 非合法 MD5md5 is invalid
1001size <= 0size is invalid
1001version 传空字符串version is empty
-目标小程序不存在或数据库更新失败由数据库层返回原始错误

7. 示例 ​

fetch 请求示例 ​

javascript
fetch("http://localhost:10009/applet/update", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440603",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "9b0cc4db-2ef0-4377-bb2b-3e7b2900be1d",
    name: { value: "OpenIM Docs Pro" },
    version: { value: "1.1.0" },
    status: { value: 2 },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例(JSON) ​

json
{
  "id": "9b0cc4db-2ef0-4377-bb2b-3e7b2900be1d",
  "name": {
    "value": "OpenIM Docs Pro"
  },
  "version": {
    "value": "1.1.0"
  },
  "status": {
    "value": 2
  }
}

成功响应示例 ​

json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

失败响应示例 ​

json
{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "md5 is invalid"
}

8. 时序流程 ​

  1. 中间件校验管理员 token。
  2. 校验 id。
  3. 查询目标小程序是否存在。
  4. 将 wrapper 字段转换为数据库更新字典,并执行字段级校验。
  5. 对目标记录执行 $set 更新并返回成功响应。

9. 变更记录 ​

  • 2026-03-31: 首版发布,基于小程序局部更新与 wrapper 字段处理逻辑补全文档。