Maas-Model-platform/docs/inside/API/MD000_System/MD000_系统服务后端API_V0.1.md

系统服务后端API文档 V0.1

基础信息

• Base URL: http://localhost:8000
• API前缀: /api/oss
• 认证方式: Bearer Token（所有接口均需要用户登录）

统一响应格式

{
  "code": 200,
  "message": "success",
  "data": {}
}

字段	类型	说明
code	int	状态码：200成功，400参数错误，401未认证，404资源不存在，500服务器错误
message	string	响应消息
data	object	响应数据

---

接口列表

1. 文件上传接口

POST /api/oss/upload

上传文件到阿里云OSS，返回公开访问URL。

请求头

参数	类型	必填	说明
Content-Type	string	是	multipart/form-data
Authorization	string	是	Bearer {token}

请求参数（Form Data）

参数	类型	必填	默认值	说明
file	file	是	-	要上传的文件，最大20MB
prefix	string	否	uploads	存储路径前缀

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/uploads/20251229/abc123def456.png",
    "filename": "example.png",
    "size": 102400
  }
}

错误响应示例

{
  "code": 400,
  "message": "文件大小超过20MB限制",
  "data": null
}

---

2. 文件下载接口

GET /api/oss/download

从OSS下载文件，返回文件流。

请求头

参数	类型	必填	说明
Authorization	string	是	Bearer {token}

请求参数（Query）

参数	类型	必填	说明
file_path	string	是	OSS文件路径（不含域名），如：uploads/20251229/abc123.png

响应

成功时返回文件流，响应头包含：

• Content-Type: 文件MIME类型
• Content-Disposition: attachment; filename=文件名

错误响应示例

{
  "code": 404,
  "message": "文件不存在",
  "data": null
}

---

3. 获取签名URL接口

GET /api/oss/signed-url

获取文件的临时签名访问URL，适用于私有文件访问。

请求头

参数	类型	必填	说明
Authorization	string	是	Bearer {token}

请求参数（Query）

参数	类型	必填	默认值	说明
file_path	string	是	-	OSS文件路径（不含域名）
expires	int	否	3600	签名URL有效期（秒）

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/uploads/20251229/abc123.png?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx",
    "expires_in": 3600
  }
}

---

错误码说明

错误码	HTTP状态码	说明
400	400	文件大小超过限制
401	401	未认证或Token无效
404	404	文件不存在
500	500	OSS服务未配置或服务器错误

---

前端对接示例

文件上传

const formData = new FormData();
formData.append('file', fileObject);
formData.append('prefix', 'images');

const response = await fetch('http://localhost:8000/api/oss/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

const data = await response.json();
if (data.code === 200) {
  console.log('文件URL:', data.data.url);
}

文件下载

const response = await fetch(
  `http://localhost:8000/api/oss/download?file_path=${encodeURIComponent('uploads/20251229/abc123.png')}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

if (response.ok) {
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'filename.png';
  a.click();
}

获取签名URL

const response = await fetch(
  `http://localhost:8000/api/oss/signed-url?file_path=${encodeURIComponent('uploads/20251229/abc123.png')}&expires=7200`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const data = await response.json();
if (data.code === 200) {
  console.log('签名URL:', data.data.url);
  // 可直接用于img标签或下载
}

---

在线文档

启动服务后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc