zyp/xiaomubiao-master

Fork 0

Files

zyp b3089a254e Initial commit

2026-05-22 16:13:20 +08:00

11 KiB

Raw Permalink Blame History

建模文件管理 API 接口说明

📋 概述

本文档描述了建模文件管理系统的REST API接口，提供3D模型文件的上传、查询、删除和下载功能。支持GLB、GLTF、B3DM和3D Tiles格式的3D模型文件，集成MinIO对象存储服务。

🏗️ 系统架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Controller    │    │     Service     │    │   MinIO存储     │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │文件上传接口  │ │◄──►│ │文件管理服务  │ │◄──►│ │3D模型文件   │ │
│ │列表查询接口  │ │    │ │             │ │    │ │             │ │
│ │删除文件接口  │ │    │ │- 文件验证   │ │    │ │- GLB格式    │ │
│ │下载文件接口  │ │    │ │- 存储管理   │ │    │ │- GLTF格式   │ │
│ └─────────────┘ │    │ │- 数据库操作 │ │    │ │- B3DM格式   │ │
└─────────────────┘    │ └─────────────┘ │    │ │- 3D Tiles   │ │
                       └─────────────────┘    │ └─────────────┘ │
                                              └─────────────────┘

🔧 基础信息

基础路径: /dji/api/modeling/models
Content-Type: multipart/form-data (上传接口), application/json (其他接口)
认证方式: 基于租户ID的多租户架构
存储服务: MinIO对象存储

📚 API接口详情

1. 上传模型文件

接口地址: POST /dji/api/modeling/models/upload

功能描述: 上传3D模型文件到指定工作空间

请求参数:

参数名	类型	必填	描述	示例值
file	MultipartFile	是	上传的文件	building.glb
workspaceId	String	是	工作空间ID	"default"
description	String	否	文件描述	"建筑模型文件"

支持的文件格式:

GLB (.glb)
GLTF (.gltf)
B3DM (.b3dm)
3D Tiles (.json)

文件大小限制: 最大100MB

请求示例:

curl -X POST "http://localhost:8080/dji/api/modeling/models/upload" \
  -F "file=@building.glb" \
  -F "workspaceId=default" \
  -F "description=建筑模型文件"

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "a1b2c3d4e5f6g7h8",
    "fileName": "building.glb",
    "fileType": "glb",
    "fileSize": 2048576,
    "uploadTime": "2024-01-15T10:30:00",
    "url": "http://27.11.11.30:9000/3d-model/default/2024/01/a1b2c3d4e5f6g7h8_building.glb",
    "workspaceId": "default",
    "description": "建筑模型文件"
  }
}

错误响应:

{
  "code": 400,
  "message": "文件上传失败: 不支持的文件格式",
  "data": null
}

2. 获取模型文件列表

接口地址: GET /dji/api/modeling/models

功能描述: 分页查询指定工作空间的模型文件列表

请求参数:

参数名	类型	必填	默认值	描述	示例值
page	Integer	否	1	页码	1
pageSize	Integer	否	10	每页大小	20
fileType	String	否	"all"	文件类型过滤	"glb"
workspaceId	String	是	-	工作空间ID	"default"

文件类型过滤选项:

all: 所有类型
glb: GLB格式
gltf: GLTF格式
b3dm: B3DM格式
3dtiles: 3D Tiles格式

请求示例:

curl -X GET "http://localhost:8080/dji/api/modeling/models?page=1&pageSize=10&fileType=glb&workspaceId=default"

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": "a1b2c3d4e5f6g7h8",
        "fileName": "building.glb",
        "fileType": "glb",
        "fileSize": 2048576,
        "uploadTime": "2024-01-15T10:30:00",
        "url": "http://27.11.11.30:9000/3d-model/default/2024/01/a1b2c3d4e5f6g7h8_building.glb",
        "workspaceId": "default",
        "description": "建筑模型文件"
      },
      {
        "id": "b2c3d4e5f6g7h8i9",
        "fileName": "tree.gltf",
        "fileType": "gltf",
        "fileSize": 1024000,
        "uploadTime": "2024-01-15T11:00:00",
        "url": "http://27.11.11.30:9000/3d-model/default/2024/01/b2c3d4e5f6g7h8i9_tree.gltf",
        "workspaceId": "default",
        "description": "树木模型"
      }
    ],
    "total": 25,
    "page": 1,
    "pageSize": 10
  }
}

3. 删除模型文件

接口地址: DELETE /dji/api/modeling/models/{id}

功能描述: 删除指定的模型文件

路径参数:

参数名	类型	必填	描述	示例值
id	String	是	文件ID	"a1b2c3d4e5f6g7h8"

请求参数:

参数名	类型	必填	描述	示例值
workspaceId	String	是	工作空间ID	"default"

请求示例:

curl -X DELETE "http://localhost:8080/dji/api/modeling/models/a1b2c3d4e5f6g7h8?workspaceId=default"

响应示例:

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

错误响应:

{
  "code": 404,
  "message": "删除文件失败: 文件不存在",
  "data": null
}

4. 获取模型下载URL

接口地址: GET /dji/api/modeling/models/{id}/download

功能描述: 获取模型文件的下载链接

路径参数:

参数名	类型	必填	描述	示例值
id	String	是	文件ID	"a1b2c3d4e5f6g7h8"

请求参数:

参数名	类型	必填	描述	示例值
workspaceId	String	是	工作空间ID	"default"

请求示例:

curl -X GET "http://localhost:8080/dji/api/modeling/models/a1b2c3d4e5f6g7h8/download?workspaceId=default"

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "downloadUrl": "http://27.11.11.30:9000/3d-model/default/2024/01/a1b2c3d4e5f6g7h8_building.glb?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
  }
}

错误响应:

{
  "code": 404,
  "message": "获取下载URL失败: 文件不存在",
  "data": null
}

📊 数据模型

ModelFileDTO - 模型文件信息

字段名	类型	描述	示例值
id	String	文件唯一标识	"a1b2c3d4e5f6g7h8"
fileName	String	原始文件名	"building.glb"
fileType	String	文件类型	"glb"
fileSize	Long	文件大小(字节)	2048576
uploadTime	LocalDateTime	上传时间	"2024-01-15T10:30:00"
url	String	文件访问URL	"http://27.11.11.30:9000/..."
workspaceId	String	工作空间ID	"default"
description	String	文件描述	"建筑模型文件"

ModelListResponse - 模型列表响应

字段名	类型	描述	示例值
records	List	模型文件列表	[...]
total	Long	总记录数	25
page	Integer	当前页码	1
pageSize	Integer	每页大小	10

DownloadUrlResponse - 下载URL响应

字段名	类型	描述	示例值
downloadUrl	String	下载链接	"http://27.11.11.30:9000/..."

🔒 错误码说明

错误码	描述	解决方案
200	成功	-
400	请求参数错误	检查请求参数格式和必填项
404	资源不存在	检查文件ID和工作空间ID
413	文件过大	文件大小不能超过100MB
415	不支持的文件类型	只支持glb、gltf、b3dm、3dtiles格式
500	服务器内部错误	联系技术支持

🚀 使用示例

JavaScript/前端示例

// 上传文件
async function uploadModel(file, workspaceId, description) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('workspaceId', workspaceId);
  formData.append('description', description);
  
  const response = await fetch('/dji/api/modeling/models/upload', {
    method: 'POST',
    body: formData
  });
  
  return await response.json();
}

// 获取文件列表
async function getModelList(workspaceId, page = 1, pageSize = 10, fileType = 'all') {
  const params = new URLSearchParams({
    workspaceId,
    page: page.toString(),
    pageSize: pageSize.toString(),
    fileType
  });
  
  const response = await fetch(`/dji/api/modeling/models?${params}`);
  return await response.json();
}

// 删除文件
async function deleteModel(id, workspaceId) {
  const response = await fetch(`/dji/api/modeling/models/${id}?workspaceId=${workspaceId}`, {
    method: 'DELETE'
  });
  
  return await response.json();
}

// 获取下载URL
async function getDownloadUrl(id, workspaceId) {
  const response = await fetch(`/dji/api/modeling/models/${id}/download?workspaceId=${workspaceId}`);
  return await response.json();
}

Java/后端示例

@RestController
public class ModelController {
    
    @Autowired
    private ModelingFileService modelingFileService;
    
    @PostMapping("/upload")
    public HttpResultResponse<ModelFileDTO> upload(
            @RequestParam("file") MultipartFile file,
            @RequestParam("workspaceId") String workspaceId,
            @RequestParam(value = "description", required = false) String description) {
        
        try {
            ModelFileDTO result = modelingFileService.uploadModel(file, workspaceId, description);
            return HttpResultResponse.success(result);
        } catch (Exception e) {
            return HttpResultResponse.errorWithType("上传失败: " + e.getMessage());
        }
    }
}

📝 注意事项

文件格式限制: 只支持GLB、GLTF、B3DM和3D Tiles格式
文件大小限制: 单个文件最大100MB
工作空间隔离: 不同工作空间的文件相互隔离
租户隔离: 基于租户ID的多租户架构
URL有效期: 下载URL有时效性，建议及时使用
并发限制: 建议控制并发上传数量，避免服务器压力过大

🔧 配置说明

MinIO配置

modeling:
  minio:
    endpoint: http://27.11.11.30:9000
    access-key: your-access-key
    secret-key: your-secret-key
    bucket-name: 3d-model

数据库配置

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/drone_p?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your-password

📞 技术支持

如有问题，请联系开发团队或查看系统日志获取详细错误信息。

最后更新时间: 2024-01-15 版本: v1.0.0

11 KiB Raw Permalink Blame History Unescape Escape

建模文件管理 API 接口说明

📋 概述

🏗️ 系统架构

🔧 基础信息

📚 API接口详情

1. 上传模型文件

2. 获取模型文件列表

3. 删除模型文件

4. 获取模型下载URL

📊 数据模型

ModelFileDTO - 模型文件信息

ModelListResponse - 模型列表响应

DownloadUrlResponse - 下载URL响应

🔒 错误码说明

🚀 使用示例

JavaScript/前端示例

Java/后端示例

📝 注意事项

🔧 配置说明

MinIO配置

数据库配置

📞 技术支持

11 KiB

Raw Permalink Blame History