audio/app-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(share): 新增 shareList 接口 + 分享码模块全链路优化

Browse Source 
- 新增 GET /audio/shareList?mac=xx 查询未过期分享码（纯 Redis，ZSET 索引）
- share:mac:{mac} 从 SET 改为 ZSET（score=expire_at），支持 ZREMRANGEBYSCORE 精确过期清理
- 空 ZSET 自动 DEL，避免 key 累积
- share:import:pending 增加 12h 兜底 TTL，防止 DB 不可用时内存泄漏
- 导入日志 field 改为 mac:code（去掉 nanotime），同 MAC+code 多次导入幂等去重
- MarkPersisted 保存/恢复 PTTL，防御性编程
- shareCreate 改为 POST + JSON body
- 全量 handler 补充 Swagger 注释，集成 swag 文档生成
- Makefile 使用 $(go env GOPATH)/bin/swag 解决 PATH 问题
This commit is contained in:
eafonyang
2026-06-12 17:07:59 +08:00
parent 8010cbd32f
commit b2aed2a6b5
12 changed files with 315 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Makefile
+3 -1
View File
@@ -1,3 +1,5 @@
SWAG := $(shell go env GOPATH)/bin/swag
.PHONY: run build test tidy swag
run:
@@ -13,4 +15,4 @@ tidy:
go mod tidy
swag:
swag init -g cmd/server/main.go -o docs --parseDependency --parseGoList
$(SWAG) init -g cmd/server/main.go -o docs --parseDependency --parseGoList
cmd/server/main.go
+1 -1
View File
@@ -31,7 +31,7 @@ import (
// @version 1.0
// @description 耳机音频参数 EQ 后端服务
//
// @BasePath /
// @BasePath /
//
// @contact.name Luxsin
docs/docs.go
+44
View File
@@ -571,6 +571,50 @@ const docTemplate = `{
}
}
}
},
"/audio/shareList": {
"get": {
"description": "根据设备 MAC 地址查询该设备尚未过期的所有分享码（仅查询 Redis，依赖 TTL 自动过期）",
"produces": [
"application/json"
],
"tags": [
"ShareCode"
],
"summary": "查询未过期分享码",
"parameters": [
{
"type": "string",
"description": "设备 MAC 地址",
"name": "mac",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "成功返回 share_codes 列表",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "参数校验失败",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"500": {
"description": "系统错误",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}`
docs/swagger.json
+44
View File
@@ -564,6 +564,50 @@
}
}
}
},
"/audio/shareList": {
"get": {
"description": "根据设备 MAC 地址查询该设备尚未过期的所有分享码（仅查询 Redis，依赖 TTL 自动过期）",
"produces": [
"application/json"
],
"tags": [
"ShareCode"
],
"summary": "查询未过期分享码",
"parameters": [
{
"type": "string",
"description": "设备 MAC 地址",
"name": "mac",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"description": "成功返回 share_codes 列表",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"400": {
"description": "参数校验失败",
"schema": {
"type": "object",
"additionalProperties": true
}
},
"500": {
"description": "系统错误",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
docs/swagger.yaml
+30
View File
@@ -376,4 +376,34 @@ paths:
summary: 创建 EQ 分享码
tags:
- ShareCode
/audio/shareList:
get:
description: 根据设备 MAC 地址查询该设备尚未过期的所有分享码（仅查询 Redis，依赖 TTL 自动过期）
parameters:
- description: 设备 MAC 地址
in: query
name: mac
required: true
type: string
produces:
- application/json
responses:
"200":
description: 成功返回 share_codes 列表
schema:
additionalProperties: true
type: object
"400":
description: 参数校验失败
schema:
additionalProperties: true
type: object
"500":
description: 系统错误
schema:
additionalProperties: true
type: object
summary: 查询未过期分享码
tags:
- ShareCode
swagger: "2.0"
internal/cache/share_code_cache.go
Vendored
+76 -11
View File
@@ -7,21 +7,24 @@ import (
"errors"
"fmt"
"math/big"
"strings"
"time"
"github.com/redis/go-redis/v9"
)
const (
shareCodeKeyPrefix = "share:"
sharePendingSet = "share:pending"
shareImportPendingHash = "share:import:pending"
shareFlushLockPref = "share:flush:lock:"
shareCodeKeyPrefix = "share:"
sharePendingSet = "share:pending"
shareImportPendingHash = "share:import:pending"
shareFlushLockPref = "share:flush:lock:"
shareImportFlushLockPref = "share:import:flush:lock:"
shareCodeLength = 5
shareCodeTTL = 30 * time.Minute
shareCodeCharset = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
shareCodeMaxRetries = 20
shareMacIndexPrefix = "share:mac:"
shareCodeLength = 5
shareCodeTTL = 30 * time.Minute
shareImportPendingTTL = 12 * time.Hour
shareCodeCharset = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
shareCodeMaxRetries = 20
fieldMacAddr = "mac_addr"
fieldIPAddr = "ip_addr"
@@ -43,6 +46,8 @@ redis.call('HSET', KEYS[1],
)
redis.call('EXPIRE', KEYS[1], tonumber(ARGV[5]))
redis.call('SADD', KEYS[2], ARGV[6])
-- ZSET: score = expire_at unix timestamp, member = share code
redis.call('ZADD', KEYS[3], tonumber(ARGV[7]), ARGV[6])
return 1
`)
@@ -86,8 +91,9 @@ func (c *ShareCodeCache) Create(ctx context.Context, macAddr, ipAddr string, eqD
}
key := shareCodeKey(code)
ok, err := shareCreateScript.Run(ctx, c.rdb, []string{key, sharePendingSet},
macAddr, ipAddr, eqJSON, expireAt.Format(time.RFC3339), int(shareCodeTTL.Seconds()), code,
macIdxKey := shareMacIndexKey(macAddr)
ok, err := shareCreateScript.Run(ctx, c.rdb, []string{key, sharePendingSet, macIdxKey},
macAddr, ipAddr, eqJSON, expireAt.Format(time.RFC3339), int(shareCodeTTL.Seconds()), code, expireAt.Unix(),
).Int()
if err != nil {
return nil, fmt.Errorf("create share code in redis: %w", err)
@@ -151,14 +157,27 @@ func (c *ShareCodeCache) ReleaseFlushLock(ctx context.Context, shareCode string)
func (c *ShareCodeCache) MarkPersisted(ctx context.Context, shareCode string) error {
key := shareCodeKey(shareCode)
// preserve remaining TTL before HSET (HSET clears TTL in some Redis versions)
remainTTL, err := c.rdb.PTTL(ctx, key).Result()
if err != nil {
return fmt.Errorf("get share code ttl: %w", err)
}
if err := c.rdb.HSet(ctx, key, fieldPersisted, "1").Err(); err != nil {
return fmt.Errorf("mark share code persisted: %w", err)
}
// restore TTL
if remainTTL > 0 {
_ = c.rdb.PExpire(ctx, key, remainTTL).Err()
}
return c.rdb.SRem(ctx, sharePendingSet, shareCode).Err()
}
func (c *ShareCodeCache) EnqueueImportLog(ctx context.Context, macAddr, shareCode, ipAddr, eqData string, expireAt time.Time) error {
field := fmt.Sprintf("%s:%s:%d", macAddr, shareCode, time.Now().UnixNano())
field := fmt.Sprintf("%s:%s", macAddr, shareCode) // 同 MAC+code 幂等，避免重复导入产生多条记录
payload, err := json.Marshal(ShareImportPendingLog{
MacAddr: macAddr,
ShareCode: shareCode,
@@ -172,6 +191,8 @@ func (c *ShareCodeCache) EnqueueImportLog(ctx context.Context, macAddr, shareCod
if err := c.rdb.HSet(ctx, shareImportPendingHash, field, payload).Err(); err != nil {
return fmt.Errorf("enqueue import log: %w", err)
}
// Fallback TTL: prevent unbounded growth if persist task is disabled or DB is down
c.rdb.Expire(ctx, shareImportPendingHash, shareImportPendingTTL)
return nil
}
@@ -195,6 +216,50 @@ func (c *ShareCodeCache) ReleaseImportFlushLock(ctx context.Context, field strin
return c.rdb.Del(ctx, shareImportFlushLockPref+field).Err()
}
func (c *ShareCodeCache) ListByMac(ctx context.Context, macAddr string) ([]*ShareCodeData, error) {
key := shareMacIndexKey(macAddr)
now := time.Now()
// Remove expired entries from ZSET (score = expire_at unix timestamp)
_, err := c.rdb.ZRemRangeByScore(ctx, key, "-inf", fmt.Sprintf("%d", now.Unix())).Result()
if err != nil && strings.Contains(err.Error(), "WRONGTYPE") {
// Old SET-type key from previous version, delete it
_ = c.rdb.Del(ctx, key).Err()
return nil, nil
}
// Get remaining (unexpired) codes
codes, err := c.rdb.ZRange(ctx, key, 0, -1).Result()
if err != nil {
return nil, fmt.Errorf("zrange mac index: %w", err)
}
if len(codes) == 0 {
// ZSET is empty, remove the key to avoid accumulating empty keys
_ = c.rdb.Del(ctx, key).Err()
return nil, nil
}
var result []*ShareCodeData
for _, code := range codes {
data, err := c.Get(ctx, code)
if err != nil {
return nil, err
}
if data == nil {
// hash already expired/removed, clean from ZSET
_ = c.rdb.ZRem(ctx, key, code).Err()
continue
}
result = append(result, data)
}
return result, nil
}
func shareMacIndexKey(macAddr string) string {
return shareMacIndexPrefix + macAddr
}
func shareCodeKey(code string) string {
return shareCodeKeyPrefix + code
}
internal/handler/curve.go
+21 -21
View File
@@ -40,17 +40,17 @@ func NewCurveHandler(repo *repository.CurveRepository, curveCache *cache.CurveCa
// ModelCurve 获取机型默认曲线（固定 target: Harman over-ear 2018）
//
// @Summary 获取机型默认频响曲线
// @Summary 获取机型默认频响曲线
// @Description 返回指定机型的频响曲线数据（fr），固定使用 Harman over-ear 2018 target
// @Tags Curve
// @Produce json
// @Param brand query string true "品牌名称"
// @Param name query string true "型号名称"
// @Param base64Resp query string false "是否返回 base64 编码响应"
// @Success 200 {object} map[string]any "成功返回 fr 数据"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} object
// @Router /audio/modelCurve [get]
// @Tags Curve
// @Produce json
// @Param brand query string true "品牌名称"
// @Param name query string true "型号名称"
// @Param base64Resp query string false "是否返回 base64 编码响应"
// @Success 200 {object} map[string]any "成功返回 fr 数据"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} object
// @Router /audio/modelCurve [get]
//
// GET /audio/modelCurve?brand=xxx&name=xxx&base64Resp=true
func (h *CurveHandler) ModelCurve(c *gin.Context) {
@@ -128,18 +128,18 @@ func (h *CurveHandler) ModelCurve(c *gin.Context) {
// GetCurve 获取目标曲线
//
// @Summary 获取目标曲线参数化 EQ
// @Summary 获取目标曲线参数化 EQ
// @Description 根据机型和目标曲线名称，计算并返回 parametric_eq 数据
// @Tags Curve
// @Produce json
// @Param brand query string true "品牌名称"
// @Param name query string true "型号名称"
// @Param target query string true "目标曲线名称"
// @Param base64Resp query string false "是否返回 base64 编码响应"
// @Success 200 {object} map[string]any "成功返回 parametric_eq 数据"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} object
// @Router /audio/getCurve [get]
// @Tags Curve
// @Produce json
// @Param brand query string true "品牌名称"
// @Param name query string true "型号名称"
// @Param target query string true "目标曲线名称"
// @Param base64Resp query string false "是否返回 base64 编码响应"
// @Success 200 {object} map[string]any "成功返回 parametric_eq 数据"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} object
// @Router /audio/getCurve [get]
//
// GET /audio/getCurve?brand=xxx&name=xxx&target=xxx&base64Resp=true
func (h *CurveHandler) GetCurve(c *gin.Context) {
internal/handler/device.go
+3 -3
View File
@@ -29,9 +29,9 @@ func NewDeviceHandler(redis *redis.Client, log *zap.Logger) *DeviceHandler {
// @Summary 上报设备信息
// @Tags Device
// @Produce json
// @Param mac query string true "设备 MAC 地址"
// @Param model query string true "设备型号"
// @Param ver query string false "固件版本号"
// @Param mac query string true "设备 MAC 地址"
// @Param model query string true "设备型号"
// @Param ver query string false "固件版本号"
// @Success 200 {object} map[string]any "操作成功"
// @Failure 500 {object} object
// @Router /audio/reportDevInfo [get]
internal/handler/model_csv.go
+11 -11
View File
@@ -29,18 +29,18 @@ func NewModelCSVHandler(s3 *storage.S3Storage, log *zap.Logger) *ModelCSVHandler
// GetModelCSV 从 S3 读取耳机 CSV 频响数据
//
// @Summary 获取耳机原始频响 CSV 数据
// @Summary 获取耳机原始频响 CSV 数据
// @Description 从 S3 读取指定机型的测量 CSV 数据，返回 frequency 和 raw 数组
// @Tags Curve
// @Produce json
// @Param brand query string true "品牌名称"
// @Param model query string true "型号名称"
// @Param form query string true "耳机类型 (in-ear/over-ear)"
// @Param base64Resp query string false "是否返回 base64 编码响应"
// @Success 200 {object} map[string]any "成功返回 frequency 和 raw 数组"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} object
// @Router /audio/getModelCSV [get]
// @Tags Curve
// @Produce json
// @Param brand query string true "品牌名称"
// @Param model query string true "型号名称"
// @Param form query string true "耳机类型 (in-ear/over-ear)"
// @Param base64Resp query string false "是否返回 base64 编码响应"
// @Success 200 {object} map[string]any "成功返回 frequency 和 raw 数组"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} object
// @Router /audio/getModelCSV [get]
//
// GET /audio/getModelCSV?brand=Abyss&model=Dinan DZ&form=over-ear&base64Resp=true
func (h *ModelCSVHandler) GetModelCSV(c *gin.Context) {
internal/handler/ota.go
+11 -11
View File
@@ -22,18 +22,18 @@ func NewOTAHandler(repo *repository.OTARepository, log *zap.Logger) *OTAHandler
// GetOTA 获取 OTA 升级信息
//
// @Summary 获取 OTA 升级信息
// @Summary 获取 OTA 升级信息
// @Description 根据设备型号和硬件版本查询最新 OTA 记录，支持黑名单过滤和定向升级逻辑
// @Tags OTA
// @Produce json
// @Param model query string true "设备型号"
// @Param hw query int true "硬件版本"
// @Param mac query string false "设备 MAC 地址"
// @Param beta query int false "是否 beta 通道 (0=否,1=是)"
// @Success 200 {object} object "成功返回 OTA 信息"
// @Failure 400 {object} object
// @Failure 500 {object} object
// @Router /audio/ota [get]
// @Tags OTA
// @Produce json
// @Param model query string true "设备型号"
// @Param hw query int true "硬件版本"
// @Param mac query string false "设备 MAC 地址"
// @Param beta query int false "是否 beta 通道 (0=否,1=是)"
// @Success 200 {object} object "成功返回 OTA 信息"
// @Failure 400 {object} object
// @Failure 500 {object} object
// @Router /audio/ota [get]
func (h *OTAHandler) GetOTA(c *gin.Context) {
modelVal := strings.TrimSpace(c.Query("model"))
hwStr := strings.TrimSpace(c.Query("hw"))
internal/handler/share_code.go
+70 -18
View File
@@ -22,16 +22,16 @@ func NewShareCodeHandler(shareCache *cache.ShareCodeCache, log *zap.Logger) *Sha
// ExportShareCode 导出分享码
//
// @Summary 创建 EQ 分享码
// @Summary 创建 EQ 分享码
// @Description 将用户的 EQ 数据生成一个 5 位分享码，有效期 30 分钟
// @Tags ShareCode
// @Accept json
// @Produce json
// @Param body body object{mac=string,eq_data=object} true "分享请求"
// @Success 200 {object} map[string]any "成功返回 share_code、expire_at、eq_data"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} map[string]any "系统错误"
// @Router /audio/shareCreate [post]
// @Tags ShareCode
// @Accept json
// @Produce json
// @Param body body object{mac=string,eq_data=object} true "分享请求"
// @Success 200 {object} map[string]any "成功返回 share_code、expire_at、eq_data"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} map[string]any "系统错误"
// @Router /audio/shareCreate [post]
//
// POST /audio/shareCreate
// Body: {"mac": "xx", "eq_data": {...}}
@@ -93,18 +93,70 @@ func (h *ShareCodeHandler) ExportShareCode(c *gin.Context) {
})
}
// ListShareCodesByMac 查询某 MAC 尚未过期的分享码
//
// @Summary 查询未过期分享码
// @Description 根据设备 MAC 地址查询该设备尚未过期的所有分享码（仅查询 Redis，依赖 TTL 自动过期）
// @Tags ShareCode
// @Produce json
// @Param mac query string true "设备 MAC 地址"
// @Success 200 {object} map[string]any "成功返回 share_codes 列表"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} map[string]any "系统错误"
// @Router /audio/shareList [get]
func (h *ShareCodeHandler) ListShareCodesByMac(c *gin.Context) {
mac := strings.TrimSpace(c.Query("mac"))
if mac == "" {
c.JSON(http.StatusOK, gin.H{"code": 400, "msg": "参数校验失败"})
return
}
ctx := c.Request.Context()
items, err := h.cache.ListByMac(ctx, mac)
if err != nil {
h.log.Error("list share codes by mac failed", zap.String("mac", mac), zap.Error(err))
c.JSON(http.StatusOK, gin.H{"code": 500, "msg": "系统错误"})
return
}
type shareItem struct {
ShareCode string `json:"share_code"`
ExpireAt string `json:"expire_at"`
EqData any `json:"eq_data"`
}
list := make([]shareItem, 0, len(items))
for _, item := range items {
var eqData any
if err := json.Unmarshal([]byte(item.EqData), &eqData); err != nil {
eqData = item.EqData
}
list = append(list, shareItem{
ShareCode: item.ShareCode,
ExpireAt: item.ExpireAt.Format("2006-01-02 15:04:05"),
EqData: eqData,
})
}
c.JSON(http.StatusOK, gin.H{
"code": 200,
"msg": "操作成功",
"share_codes": list,
})
}
// ImportShareCode 导入分享码
//
// @Summary 导入 EQ 分享码
// @Summary 导入 EQ 分享码
// @Description 根据分享码获取他人分享的 EQ 数据
// @Tags ShareCode
// @Produce json
// @Param mac query string true "设备 MAC 地址"
// @Param shareCode query string true "5 位分享码"
// @Success 200 {object} map[string]any "成功返回 eq_data"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} map[string]any "系统错误"
// @Router /audio/shareAccept [get]
// @Tags ShareCode
// @Produce json
// @Param mac query string true "设备 MAC 地址"
// @Param shareCode query string true "5 位分享码"
// @Success 200 {object} map[string]any "成功返回 eq_data"
// @Failure 400 {object} map[string]any "参数校验失败"
// @Failure 500 {object} map[string]any "系统错误"
// @Router /audio/shareAccept [get]
//
// GET /audio/shareAccept?mac=xx&shareCode=ABC12
func (h *ShareCodeHandler) ImportShareCode(c *gin.Context) {
internal/router/router.go
+1
View File
@@ -68,6 +68,7 @@ func New(log *zap.Logger, db *sql.DB, searchClient *search.Client, rdb *redis.Cl
audio.GET("/modelCurve", curve.ModelCurve)
audio.GET("/getModelCSV", modelCSV.GetModelCSV)
audio.POST("/shareCreate", shareCode.ExportShareCode)
audio.GET("/shareList", shareCode.ListShareCodesByMac)
audio.GET("/shareAccept", shareCode.ImportShareCode)
}