跳到主要内容
xray.top

StockApi

StockApi 是一个面向股票数据查询与访问控制场景的 Go 单体服务。 它将公开只读数据 API、用户门户和管理员后台统一在一个项目中，目标是提供一套清晰、可运行、便于联调和演示的股票数据服务样例。

6/1/2026
GitHubDemo
apigoredisssrstock#api#go#redis#ssr#stock

StockApi

项目概述

StockApi 是一个基于 Go 的单体服务，当前统一承载三类能力：

项目当前定位是“内部可用的预览版系统”：

当前治理结论

这次项目治理后，当前口径统一为：

这几条是当前项目的硬边界，不再保留旧兼容文案。

文档结构与优先级

仓库当前保留两层文档：

当前生效文档

归档文档

阅读优先级建议如下：

  1. 公开接口路径、字段、参数和值域，以 docs/api.md 为准
  2. 运行方式、环境变量、门户流程、数据库说明，以本文档为准
  3. 归档文档仅作为历史背景参考，不作为当前运行口径

系统组成

1. 公开数据 API

公开接口统一挂在 /api/v1 下。

当前主要数据能力包括：

公开接口文档入口：

2. 用户门户

当前用户侧页面包括：

用户当前可执行的动作：

3. 管理后台

当前管理员侧页面包括：

管理员当前可执行的动作：

公开接口边界

Swagger 覆盖范围

Swagger 只描述以下公开接口：

不进入 Swagger 的路径

以下路径是站内 SSR 页面，不属于公开 API 文档：

鉴权、账号与 Token

公开 API 鉴权

除 /api/v1/meta/health 外，其余公开接口默认要求：

Http
Authorization: Bearer <token>

账号模型

当前统一账号表为 user_account，角色只分两级：

登录方式统一为：

当前没有密码登录。

管理员识别规则

当前管理员识别规则已经收口为：

不再使用：

Token 规则

当前 token 规则如下：

当前支持的只读 scope：

Token 申请与审核

当前申请流程仍使用独立 SSR 页面：

申请记录写入：

审核通过后创建实际 token，写入：

限流

当前限流实现为：

当前响应头：

X-RateLimit-Reset 当前尚未实现。

数据库说明

本项目自身初始化的表

stockapi-initdb 只初始化以下 4 张权限/门户相关表：

表定义见：

外部依赖的业务数据表

股票和板块等业务数据不由本项目建表，而是假设已经存在于 stocks 数据库。

当前核心依赖表包括：

这些表的字段、枚举和值域定义，请看：

环境变量

当前项目运行只认环境变量。

模板文件：

建议先复制：

Bash
cp .env.example .env

必要环境变量

MySQL：

Redis：

服务自身：

注册邮件：

辅助项：

Docker 默认口径

既然当前项目只考虑 Docker 运行，.env.example 默认采用：

这意味着容器会直接连接宿主机上的 MySQL 与 Redis。

敏感信息原则

以下内容必须放在 .env 或外部环境变量中，不能再写回仓库配置文件：

Docker 运行

1. 准备环境变量

Bash
cp .env.example .env

填写实际数据库、Redis、邮件和 TOTP 主密钥。

2. 初始化权限表

Bash
docker compose --profile app run --rm api /app/stockapi-initdb

这一步只会初始化：

3. 构建并启动

Bash
docker compose --profile app build api
docker compose --profile app up -d api

如果你明确要关闭 BuildKit，直接走普通 Docker 构建：

Bash
DOCKER_BUILDKIT=0 COMPOSE_DOCKER_CLI_BUILD=0 docker compose --profile app build api
DOCKER_BUILDKIT=0 COMPOSE_DOCKER_CLI_BUILD=0 docker compose --profile app up -d api

4. 访问入口

典型流程

用户流程

  1. 打开 /portal/register
  2. 选择邮箱服务商并发送验证码
  3. 完成邮箱验证后绑定 TOTP
  4. 打开 /portal/login 登录
  5. 进入 /portal/
  6. 如需调用 API，访问 /apply 提交 token 申请
  7. 等待管理员审核
  8. 审核通过后在 /portal/ 查看 token 属性、状态和当前额度
  9. 使用 Bearer Token 调用 /api/v1/*

管理员流程

  1. 先在数据库中将管理员邮箱标记为 user_account.role='admin'
  2. 打开 /portal/login
  3. 首次完成管理员 TOTP 初始化
  4. 登录后进入 /portal/admin/
  5. 在 /portal/admin/applications 审核申请
  6. 发放 token 后，用户在门户中查看，管理员在后台继续管理额度、状态和限流

代码结构

入口命令

应用装配

负责：

配置层

当前只负责：

不再负责历史文件配置或配置文件路径兼容逻辑。

平台适配层

业务与门户服务

HTTP 层

本地开发命令

虽然运行形态只推荐 Docker，但开发期仍保留这些本地命令：

格式化：

Bash
make fmt

测试：

Bash
make test

初始化权限表：

Bash
make initdb

本地直接启动服务：

Bash
make run

生成 Swagger：

Bash
make docs

辅助加密 TOTP secret：

Bash
make admin-encrypt-totp

已知边界

当前系统已经能内部使用，但仍有明确边界：

免责说明

本项目中的股票、板块、快照、涨停池和相关数据，本质上依赖公开互联网来源及既有数据库整理结果。

当前项目更适合：

请勿将本项目及其数据直接用于商业用途、投资建议、交易决策或其他高风险场景。因使用本项目产生的任何直接或间接损失，项目维护方不承担责任。