399 lines
11 KiB
Markdown
399 lines
11 KiB
Markdown
# 建模文件管理 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
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X POST "http://localhost:8080/dji/api/modeling/models/upload" \
|
||
-F "file=@building.glb" \
|
||
-F "workspaceId=default" \
|
||
-F "description=建筑模型文件"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"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": "建筑模型文件"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"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格式
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "http://localhost:8080/dji/api/modeling/models?page=1&pageSize=10&fileType=glb&workspaceId=default"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"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" |
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X DELETE "http://localhost:8080/dji/api/modeling/models/a1b2c3d4e5f6g7h8?workspaceId=default"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "删除文件失败: 文件不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取模型下载URL
|
||
|
||
**接口地址**: `GET /dji/api/modeling/models/{id}/download`
|
||
|
||
**功能描述**: 获取模型文件的下载链接
|
||
|
||
**路径参数**:
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| id | String | 是 | 文件ID | "a1b2c3d4e5f6g7h8" |
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| workspaceId | String | 是 | 工作空间ID | "default" |
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X GET "http://localhost:8080/dji/api/modeling/models/a1b2c3d4e5f6g7h8/download?workspaceId=default"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"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=..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"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<ModelFileDTO> | 模型文件列表 | [...] |
|
||
| 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/前端示例
|
||
|
||
```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/后端示例
|
||
|
||
```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());
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **文件格式限制**: 只支持GLB、GLTF、B3DM和3D Tiles格式
|
||
2. **文件大小限制**: 单个文件最大100MB
|
||
3. **工作空间隔离**: 不同工作空间的文件相互隔离
|
||
4. **租户隔离**: 基于租户ID的多租户架构
|
||
5. **URL有效期**: 下载URL有时效性，建议及时使用
|
||
6. **并发限制**: 建议控制并发上传数量，避免服务器压力过大
|
||
|
||
---
|
||
|
||
## 🔧 配置说明
|
||
|
||
### MinIO配置
|
||
```yaml
|
||
modeling:
|
||
minio:
|
||
endpoint: http://27.11.11.30:9000
|
||
access-key: your-access-key
|
||
secret-key: your-secret-key
|
||
bucket-name: 3d-model
|
||
```
|
||
|
||
### 数据库配置
|
||
```yaml
|
||
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
|