搜索小程序

1. 接口定位

• 接口名称: 搜索小程序
• 所属域: admin/applet
• 业务目标: 按名称、记录 ID、AppID 或版本号分页检索小程序配置

2. 请求定义

• Method: POST
• Path: /applet/search
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 幂等

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
keyword	否	string	对 name、id、app_id、version 做不区分大小写模糊匹配；为空时等价于全量搜索
pagination	是	object	分页参数

pagination 字段

字段	必填	类型	说明
pageNumber	是	int32	页码，从 1 开始
showNumber	是	int32	每页条数，大于 0

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
total	uint32	命中的小程序总数
applets	array<object>	当前页小程序列表

applets 元素字段

字段	类型	说明
id	string	小程序记录 ID
name	string	名称
appID	string	业务 AppID
icon	string	图标地址
url	string	访问地址
md5	string	摘要值
size	int64	安装包大小
version	string	版本号
priority	uint32	排序优先级
status	uint32	状态：1 上架，2 下架
createTime	int64	创建时间，Unix 毫秒时间戳

5. 业务规则

• 仅管理员可以调用。
• keyword 会对 name、id、app_id、version 同时执行 MongoDB $regex 模糊匹配，忽略大小写。
• 返回数据直接来自本地小程序配置表，不额外拼装其他服务数据。

6. 错误码与失败场景

错误码	场景	典型报错
1001	pagination 为空	pagination is empty
1001	pageNumber < 1	pageNumber is invalid
1001	showNumber < 1	showNumber is invalid
-	数据库搜索失败	由数据库层返回原始错误

7. 示例

fetch 请求示例

fetch("http://localhost:10009/applet/search", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440604",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "docs",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "keyword": "docs",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "applets": [
      {
        "id": "9b0cc4db-2ef0-4377-bb2b-3e7b2900be1d",
        "name": "OpenIM Docs",
        "appID": "docs-center",
        "icon": "https://example.com/applet.png",
        "url": "https://example.com/applet/index.html",
        "md5": "4e5d54f50370b936533dfcb2f3540a8b",
        "size": 204800,
        "version": "1.0.0",
        "priority": 10,
        "status": 1,
        "createTime": 1767225600000
      }
    ]
  }
}

失败响应示例

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

8. 时序流程

1. 中间件校验管理员 token。
2. 校验分页参数。
3. 按 keyword 在小程序表中分页搜索。
4. 将数据库记录映射成 AppletInfo 列表。
5. 返回 total + applets。

9. 变更记录

• 2026-03-31: 首版发布，基于小程序分页搜索逻辑补全文档。