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

最新推荐文章于 2025-08-23 22:34:19 发布

原创最新推荐文章于 2025-08-23 22:34:19 发布 · 912 阅读

15 ·

CC 4.0 BY-SA版权

文章标签：

#golang

softHub 专栏收录该内容

20 篇文章

订阅专栏

文章目录

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

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

前言

在Softhub软件下载站的开发过程中，我们终于来到了用户端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:"文件流"`
}

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