Outline项目API上传附件问题解析与解决方案

问题背景

在使用Outline项目的API进行附件上传时，开发者遇到了一个常见的技术障碍。当尝试通过API将图片从旧CMS迁移到Outline页面时，系统返回了验证错误，提示"size: Expected number, received string"。这个问题不仅出现在脚本调用中，使用Postman测试时也复现了相同的结果。

错误分析

从技术角度看，这个错误表明API服务端期望接收一个数值类型的size参数，但实际接收到的却是字符串类型。这是典型的API参数类型不匹配问题，在RESTful API开发中较为常见。

解决方案详解

1. 正确的API调用方式

Outline API设计上要求使用JSON格式的请求体，而不是传统的表单编码(form-encoded)格式。这是许多开发者容易忽略的关键点。正确的请求应该包含以下必需参数：

• name: 附件名称
• documentId: 目标文档ID
• contentType: 文件MIME类型
• size: 文件大小(必须为数值类型)

2. 完整请求示例

一个完整的cURL请求示例如下：

curl https://myoutline.com/api/attachments.create \
  --request POST \
  --header 'Authorization: Bearer your_api_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "example.png",
    "documentId": "af2d42d1-553b-4a2b-9ae1-ba4393285955",
    "contentType": "image/png",
    "size": 3037
  }'

3. 替代方案：Markdown嵌入

对于图片文件，Outline还支持通过Markdown语法直接嵌入。开发者可以将图片进行base64编码后，使用标准的Markdown图片语法插入到文档中。系统会自动将其转换为附件存储。这种方法特别适合批量迁移场景。

技术要点总结

1. 参数类型严格校验：API服务端对参数类型有严格校验，特别是数值型参数必须确保传递的是数字而非字符串。

2. 内容类型头设置：必须正确设置Content-Type: application/json请求头，告知服务端请求体格式。

3. 文件大小获取：在上传前需要准确获取文件大小(字节数)，并确保以数值类型传递。

4. 认证机制：不要忘记在请求头中包含有效的Bearer Token进行身份验证。

最佳实践建议

1. 在开发脚本时，建议先使用Postman等工具测试API调用，验证参数格式正确后再进行代码实现。

2. 对于批量迁移场景，可以考虑先获取所有文档的ID和结构，再规划附件上传顺序。

3. 实现错误重试机制，特别是对于网络不稳定的环境。

4. 对于大文件上传，建议分块处理并监控进度。

通过理解这些技术细节和遵循最佳实践，开发者可以更高效地利用Outline API完成内容迁移工作。