zhibo/模块文档/13-文件上传模块.md

文件上传模块

模块概述

文件上传模块负责处理图片、视频等媒体文件的上传功能，为用户头像、作品发布、消息图片等功能提供支持。

相关文件

• FileUploadResponse.java - 文件上传响应模型
• PublishWorkActivity.java - 作品发布界面（使用文件上传）
• EditProfileActivity.java - 编辑资料界面（使用头像上传）

---

接口列表

1. 上传图片

接口地址: POST /api/front/user/upload/image

请求方式: multipart/form-data

请求参数:

file: File          // 图片文件（必填）
model: string       // 模块标识（必填）
pid: integer        // 关联ID（必填）

model参数说明:

• avatar - 用户头像
• work - 作品图片
• message - 聊天图片
• cover - 封面图片

返回数据 (FileUploadResponse):

{
  "code": 200,
  "msg": "上传成功",
  "data": {
    "url": "string",           // 文件访问URL
    "fileName": "string",      // 文件名
    "fileSize": "long",        // 文件大小（字节）
    "fileType": "string",      // 文件类型
    "uploadTime": "long"       // 上传时间戳
  }
}

---

2. 上传视频

接口地址: POST /api/front/upload/work/video

请求方式: multipart/form-data

请求参数:

file: File          // 视频文件（必填）
model: string       // 模块标识（必填）
pid: integer        // 关联ID（必填）

model参数说明:

• work - 作品视频
• message - 聊天视频

返回数据 (FileUploadResponse):

{
  "code": 200,
  "msg": "上传成功",
  "data": {
    "url": "string",           // 文件访问URL
    "fileName": "string",      // 文件名
    "fileSize": "long",        // 文件大小（字节）
    "fileType": "string",      // 文件类型
    "duration": "integer",     // 视频时长（秒）
    "width": "integer",        // 视频宽度
    "height": "integer",       // 视频高度
    "uploadTime": "long"       // 上传时间戳
  }
}

---

功能说明

支持的文件类型

图片格式:

• JPG/JPEG
• PNG
• GIF
• WEBP

视频格式:

• MP4
• AVI
• MOV
• FLV

文件大小限制

• 图片：最大 10MB
• 视频：最大 100MB

上传流程

1. 选择文件
2. 构建 multipart/form-data 请求
3. 调用上传接口
4. 获取返回的文件URL
5. 使用URL进行后续操作（如发布作品、更新头像等）

---

使用示例

Android代码示例

上传图片

// 创建文件部分
File imageFile = new File(imagePath);
RequestBody fileBody = RequestBody.create(
    MediaType.parse("image/*"), 
    imageFile
);
MultipartBody.Part filePart = MultipartBody.Part.createFormData(
    "file", 
    imageFile.getName(), 
    fileBody
);

// 创建其他参数
RequestBody model = RequestBody.create(
    MediaType.parse("text/plain"), 
    "avatar"
);
RequestBody pid = RequestBody.create(
    MediaType.parse("text/plain"), 
    String.valueOf(userId)
);

// 调用接口
ApiService apiService = ApiClient.getService(context);
Call<ApiResponse<FileUploadResponse>> call = 
    apiService.uploadImage(filePart, model, pid);

call.enqueue(new Callback<ApiResponse<FileUploadResponse>>() {
    @Override
    public void onResponse(Call<ApiResponse<FileUploadResponse>> call, 
                         Response<ApiResponse<FileUploadResponse>> response) {
        if (response.isSuccessful() && response.body() != null) {
            ApiResponse<FileUploadResponse> apiResponse = response.body();
            if (apiResponse.getCode() == 200) {
                String imageUrl = apiResponse.getData().getUrl();
                // 使用图片URL
            }
        }
    }

    @Override
    public void onFailure(Call<ApiResponse<FileUploadResponse>> call, Throwable t) {
        // 处理错误
    }
});

上传视频

// 创建文件部分
File videoFile = new File(videoPath);
RequestBody fileBody = RequestBody.create(
    MediaType.parse("video/*"), 
    videoFile
);
MultipartBody.Part filePart = MultipartBody.Part.createFormData(
    "file", 
    videoFile.getName(), 
    fileBody
);

// 创建其他参数
RequestBody model = RequestBody.create(
    MediaType.parse("text/plain"), 
    "work"
);
RequestBody pid = RequestBody.create(
    MediaType.parse("text/plain"), 
    String.valueOf(userId)
);

// 调用接口
ApiService apiService = ApiClient.getService(context);
Call<ApiResponse<FileUploadResponse>> call = 
    apiService.uploadVideo(filePart, model, pid);

call.enqueue(new Callback<ApiResponse<FileUploadResponse>>() {
    @Override
    public void onResponse(Call<ApiResponse<FileUploadResponse>> call, 
                         Response<ApiResponse<FileUploadResponse>> response) {
        if (response.isSuccessful() && response.body() != null) {
            ApiResponse<FileUploadResponse> apiResponse = response.body();
            if (apiResponse.getCode() == 200) {
                String videoUrl = apiResponse.getData().getUrl();
                int duration = apiResponse.getData().getDuration();
                // 使用视频URL和时长
            }
        }
    }

    @Override
    public void onFailure(Call<ApiResponse<FileUploadResponse>> call, Throwable t) {
        // 处理错误
    }
});

---

错误处理

错误码	说明
400	参数错误或文件格式不支持
401	未登录
413	文件过大
415	不支持的文件类型
500	服务器错误

---

注意事项

1. 所有上传接口都需要登录认证
2. 上传前建议先压缩图片以提高上传速度
3. 视频上传时间较长，建议显示进度条
4. 上传失败时可以重试
5. model和pid参数用于后端文件管理和关联
6. 返回的URL是完整的访问地址，可直接使用
7. 建议在上传前检查文件大小和格式