学生异动视图只读 API

从 MySQL 视图 vw_jw_student_change_export 拉取数据，供教务或其它系统调用。

Python：开发与生产建议 3.7.9（与现网一致）。
依赖：见 requirements.txt（Flask 2.0.x + PyMySQL）。

配置文件与环境对应关系

本目录文件	后端配置来源	Spring 环境
`config.dev.ini`	`backend/ruoyi-admin/src/main/resources/application-dev.yml`（`spring.datasource.dynamic.datasource.master`）	dev（测试/开发）
`config.prod.ini`	`backend/ruoyi-admin/src/main/resources/application-prod.yml`（同上）	prod（生产）

主机、端口、库名、用户名、密码已与上述 YAML 中 master 数据源保持一致；后端配置变更时请同步修改对应 INI。

安装

开发机（推荐虚拟环境）

cd 跟教务系统同步学生异动信息/api_service
python3.7 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Linux 生产环境：`pip3：未找到命令` / `No module named pymysql`

很多最小化系统只有 python3，没有独立的 pip3 命令。请用 当前解释器自带的 pip 模块 安装依赖，例如：

cd /path/to/api_service

# 1）优先尝试（与 python3 一一对应）
python3 -m pip install -r requirements.txt

# 若 `python3 -m pip` 报 No module named pip，先装系统级 pip（需 root）：
#   CentOS 7 / 部分 RHEL：
#     yum install -y python3-pip
#   CentOS 8+ / RHEL 8+ / Fedora：
#     dnf install -y python3-pip
# 装完再执行：
python3 -m pip install -r requirements.txt

# 若无 yum/dnf 或仓库无 python3-pip，可用官方引导脚本（任选其一 Python 版本需为 3.7+）：
#   curl -sS https://bootstrap.pypa.io/pip/3.7/get-pip.py -o get-pip.py
#   python3 get-pip.py
#   python3 -m pip install -r requirements.txt
# （3.7 专用 get-pip 见：https://bootstrap.pypa.io/pip/3.7/get-pip.py ）

确认：

python3 -c "import pymysql, flask; print('ok')"

启动时请用 python3 app.py（或与安装依赖时相同的 python3），避免混用 python 指向旧版 2.x。

选用配置并启动

测试/开发（与 dev 库一致）：

cp config.dev.ini config.ini
python app.py

或直接：

export JW_CX_CONFIG="$(pwd)/config.dev.ini"
python app.py

生产：

export JW_CX_CONFIG=/opt/jw-cx/config.prod.ini
python app.py

配置文件说明

环境变量	说明
`JW_CX_CONFIG`	配置文件路径；不设则使用当前工作目录下的 `config.ini`（相对路径相对于进程启动时的工作目录）

模板见 config.ini.example。config.ini 已在 .gitignore 中忽略，避免把本地覆盖提交上去。

INI 节说明

[database]：host、port、user、password、database
[api]：

键	说明
`api_key`	与请求头 `X-Jw-Cx-Key` 一致
`bind_host` / `bind_port`	HTTP 监听（仅直接运行 `python app.py` 时生效）
`page_size`	默认每页条数；请求可带 `page_size` Query 覆盖，程序内限制 1～5000
`recent_days`	默认近 N 天；请求可带 `recent_days` / `days` 覆盖，程序内限制 1～3660

密钥校验

所有 /api/v1/student-changes 请求必须在 HTTP Header 中携带：

X-Jw-Cx-Key: <与配置文件中 [api] api_key 相同，默认 JWCX001>

/health 不做密钥校验。

生产进程（gunicorn）

pip install 'gunicorn>=20.1.0,<21'
export JW_CX_CONFIG=/path/to/config.prod.ini
gunicorn -w 2 -b 0.0.0.0:5050 app:app

监听地址/端口以 gunicorn 的 -b 为准；bind_port 仅对直接运行 python app.py 有效。

接口说明

GET `/health`

返回 {"status":"ok"}。

GET `/api/v1/student-changes`

数据范围：仅 提交时间 在最近 N 个自然日内的记录；N 由 recent_days（或 days）指定，未传则使用配置 [api] recent_days（默认 30）。
分页：每页条数 page_size 可传 Query 覆盖，未传则使用 [api] page_size（默认 500）。

Query	说明	未传时的默认值
`page`	页码，从 1 开始	`1`
`page_size`	每页条数，有效范围 1～5000	`[api] page_size`
`recent_days`	查询近 N 天（与视图列「提交时间」比较），有效范围 1～3660	`[api] recent_days`
`days`	与 `recent_days` 同义，二选一即可	（同上）

成功响应中除 data、page、page_size、total 外，还包括：

JSON 字段	说明
`filter_recent_days`	本次请求实际生效的近 N 天（含 URL 覆盖后的值）
`filter_by_column`	固定为 `提交时间`（筛选字段名）

未授权（HTTP 401）：未带或错误的 X-Jw-Cx-Key。

调用示例

# 使用配置中的 page_size、recent_days
curl -s -H "X-Jw-Cx-Key: JWCX001" \
  "http://127.0.0.1:5050/api/v1/student-changes?page=1"

# 指定每页 50 条、近 7 天
curl -s -H "X-Jw-Cx-Key: JWCX001" \
  "http://127.0.0.1:5050/api/v1/student-changes?page=1&page_size=50&recent_days=7"

安全说明

config.dev.ini / config.prod.ini 含数据库凭据，与后端 YAML 同源；请按公司规范控制仓库可见性与部署权限。
建议数据库侧使用仅对视图 vw_jw_student_change_export 有 SELECT 的专用账号，与后端 root 分离。
生产将 api_key 换为强随机串，并走 HTTPS；必要时加网络白名单。

README.md 5.6 KB История Исходник