OpenIM Chat Docs

Appearance

导入模板下载 ​

1. 接口定位 ​

  • 接口名称: 导入模板下载
  • 所属域: admin/user
  • 业务目标: 下载批量导入用户所需的 XLSX 模板文件

2. 请求定义 ​

  • Method: GET
  • Path: /user/import/xlsx
  • Content-Type: 无需请求体
  • operationID: 兼容建议传入，但当前实现不强依赖
  • 鉴权: 无
  • 幂等性: 幂等

3. 请求参数 ​

Header 参数 ​

字段必填类型说明
operationID否string链路追踪 ID
If-None-Match否string模板 ETag；命中时返回 304 Not Modified

Query 参数 ​

  • 无。

4. 响应结构 ​

成功响应 ​

  • 响应体为二进制 XLSX 文件，不使用统一 JSON 包裹。

关键响应头 ​

Header说明
Content-Disposition固定为 attachment; filename=template.xlsx
Content-Transfer-Encoding固定为 binary
Content-Description固定为 File Transfer
Content-Length模板字节长度
ETag模板二进制内容的 MD5 值
Content-Typeapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet

5. 业务规则 ​

  • 本接口无需鉴权。
  • 服务端会对内置模板二进制计算 MD5，并作为 ETag 返回。
  • 如果请求头 If-None-Match 与当前模板 MD5 完全一致，则直接返回 304 Not Modified，不再返回文件内容。

6. 错误码与失败场景 ​

  • 本接口主要通过 HTTP 状态码表达结果：
    • 200 OK: 返回模板文件
    • 304 Not Modified: 客户端持有的模板仍是最新版本

7. 示例 ​

fetch 请求示例 ​

javascript
fetch("http://localhost:10009/user/import/xlsx", {
  method: "GET",
  headers: {
    "If-None-Match": "4e5d54f50370b936533dfcb2f3540a8b",
  },
})
  .then((res) => {
    if (res.status === 304) return null;
    return res.blob();
  })
  .then((blob) => console.log(blob));

200 OK 响应头示例 ​

http
Content-Disposition: attachment; filename=template.xlsx
Content-Transfer-Encoding: binary
Content-Description: File Transfer
Content-Length: 12345
ETag: 4e5d54f50370b936533dfcb2f3540a8b
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

8. 时序流程 ​

  1. 计算内置模板内容的 MD5。
  2. 比较请求头 If-None-Match 是否命中当前模板 ETag。
  3. 若命中则返回 304。
  4. 若未命中则设置下载响应头并返回模板二进制内容。

9. 变更记录 ​

  • 2026-03-31: 首版发布，基于导入模板下载接口的 ETag 与二进制响应逻辑补全文档。