Initial commit
This commit is contained in:
398
API接口说明.md
Normal file
398
API接口说明.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# 建模文件管理 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
|
||||
Reference in New Issue
Block a user