Softhub软件下载站实战开发（十七）：用户端API设计

Softhub软件下载站实战开发（十七）：用户端API设计

前言

在Softhub软件下载站的开发过程中，我们终于来到了用户端API的设计阶段！ 用户端API是整个系统与前端交互的核心桥梁，良好的API设计能极大提升开发效率和用户体验。本篇将详细介绍我们的用户端API设计方案。

用户端API概览

我们的用户端API主要分为以下几个模块：

用户端API

分类管理

首页管理

资源集管理

软件管理

资源下载

1. 分类管理API

分类是软件的组织方式，我们设计了简洁的分类列表接口：

type DsCategoryListReq struct {
	g.Meta `path:"/category/list" method:"get" tags:"分类表" summary:"分类表-列表"`
}

type DsCategoryListRes struct {
	g.Meta         `mime:"application/json" example:"string"`
	DsCategoryList []*model.DsCategoryInfo `json:"dsCategoryList"`
}

• 路径: /category/list
• 方法: GET
• 返回: 所有分类的列表

2. 首页API

首页需要展示分类及其热门软件：

type DsIndexReq struct {
	g.Meta `path:"/index" method:"get" tags:"首页" summary:"首页"`
}

type DsIndexRes struct {
	g.Meta       `mime:"application/json" example:"string"`
	CategoryList []*CategoryWithSoftware `json:"categoryList"`
}

// CategoryWithSoftware 分类及其软件列表
type CategoryWithSoftware struct {
	Category     *model.DsCategoryInfo   `json:"category"`     // 分类信息
	SoftwareList []*model.DsSoftwareInfo `json:"softwareList"` // 该分类下的软件列表（最近20个）
}

type HealthCheckReq struct {
	g.Meta `path:"/health" method:"get" tags:"首页" summary:"健康检查"`
}

type HealthCheckRes struct {
	g.Meta `mime:"application/json" example:"string"`
	Msg    string `json:"msg"`
}

• 特色: 每个分类附带最新20个软件，提升首页内容丰富度
• 健康检查: 我们还提供了简单的健康检查接口 /health

3. 资源集管理API

资源集是软件的合集，我们提供了：

type DsResourceSetListReq struct {
	g.Meta `path:"/resourceSet/list" method:"get" tags:"资源集管理" summary:"用户端资源集列表"`
	commonApi.PageReq
	Name string `json:"name"`
}

type DsResourceSetListRes struct {
	g.Meta `mime:"application/json" example:"string"`
	commonApi.ListRes
	DsResourceSetList []*model.DsResourceSetInfo `json:"dsResourceSetList"`
}

type DsResourceSetSoftwareListReq struct {
	g.Meta `path:"/resourceSet/softwareList" method:"get" tags:"资源集软件关系" summary:"获取资源集下的软件列表"`
	SetId  int `json:"setId" v:"required#资源集id不能为空"`
}

type DsResourceSetSoftwareListRes struct {
	g.Meta       `mime:"application/json" example:"string"`
	SoftwareList []*model.DsSoftwareInfo `json:"softwareList"`
}

• 功能:
  • 分页获取资源集列表
  • 获取指定资源集下的软件列表

4. 软件管理API

软件是系统的核心，我们设计了丰富的接口：

软件列表

软件详情

默认资源

所有资源

具体接口设计：

type DsSoftwareListReq struct {
	g.Meta `path:"/software/list" method:"get" tags:"软件表" summary:"软件表-列表"`
	commonApi.PageReq
	CategoryId uint   `p:"categoryId"`
	KeyWord    string `p:"keyword"`
}

type DsSoftwareListRes struct {
	g.Meta `mime:"application/json" example:"string"`
	commonApi.ListRes
	DsSoftwareList []*model.DsSoftwareInfo `json:"dsSoftwareList"`
}

type DsSoftwareDetailReq struct {
	g.Meta `path:"/software/detail" method:"get" tags:"软件表" summary:"软件表-详情"`
	Id     int64 `p:"id" v:"required#id不能为空"`
}

type DsSoftwareDetailRes struct {
	g.Meta `mime:"application/json" example:"string"`
	*model.DsSoftwareInfo
}

// 获取软件默认资源
type DsSoftwareDefaultResourceReq struct {
	g.Meta `path:"/software/defaultResource" method:"get" tags:"软件表" summary:"获取软件默认资源"`
	Id     int64 `p:"id" v:"required#软件id不能为空"`
}

type DsSoftwareDefaultResourceRes struct {
	g.Meta   `mime:"application/json" example:"string"`
	Resource *model.DsSoftwareResourceInfo `json:"resource"`
}

// 获取软件全部资源
type DsSoftwareAllResourcesReq struct {
	g.Meta `path:"/software/allResources" method:"get" tags:"软件表" summary:"获取软件全部资源"`
	Id     int64 `p:"id" v:"required#软件id不能为空"`
}

type DsSoftwareAllResourcesRes struct {
	g.Meta    `mime:"application/json" example:"string"`
	Resources []*model.DsSoftwareResourceInfo `json:"resources"`
}

5. 资源下载API ⬇️

最后是核心的下载功能：

type DsSoftwareResourceDownloadReq struct {
	g.Meta `path:"/resource/download" method:"get" tags:"软件资源表" summary:"用户端软件资源表-下载"`
	Id     interface{} `p:"id" v:"required#id不能为空"`
}

type DsSoftwareResourceDownloadRes struct {
	g.Meta `name:"文件流"`
}

• 特点: 直接返回文件流，支持断点续传
• 安全: 需要验证用户权限

API设计原则 ‍

1. RESTful风格: 使用合适的HTTP方法和状态码
2. 一致性: 所有API返回统一格式
3. 文档化: 每个API都有清晰的注释和标签
4. 验证: 关键参数都有验证规则
5. 性能: 列表接口都支持分页

所有API都遵循GFast框架的规范，充分利用了GoFrame提供的强大功能，如自动路由注册、参数验证等。

---

softhub系列往期文章

1. Softhub软件下载站实战开发（一）：项目总览
2. Softhub软件下载站实战开发（二）：项目基础框架搭建
3. Softhub软件下载站实战开发（三）：平台管理模块实战
4. Softhub软件下载站实战开发（四）：代码生成器设计与实现
5. Softhub软件下载站实战开发（五）：分类模块实现
6. Softhub软件下载站实战开发（六）：软件配置面板实现
7. Softhub软件下载站实战开发（七）：集成MinIO实现文件存储功能
8. Softhub软件下载站实战开发（八）：编写软件后台管理
9. Softhub软件下载站实战开发（九）：编写软件配置管理界面
10. Softhub软件下载站实战开发（十）：实现图片视频上传下载接口
11. Softhub软件下载站实战开发（十一）：软件分片上传接口实现
12. Softhub软件下载站实战开发（十二）：软件管理编辑页面实现
13. Softhub软件下载站实战开发（十三）：软件管理前端分片上传实现
14. Softhub软件下载站实战开发（十四）：软件收藏集设计
15. Softhub软件下载站实战开发（十五）：仪表盘API设计
16. Softhub软件下载站实战开发（十六）：仪表盘前端设计与实现