MovieApp 开发文档

Appearance

接口概览 ​

移动端所有接口由后端 MobileModule 提供，对应路径前缀为 /api/mobile/v1。接口使用统一的响应包装格式：

json
{
  "code": 0,
  "message": "OK",
  "data": {},
  "originUrl": "/api/mobile/v1/xxx"
}

基础信息 ​

  • 域名：根据环境区分，例如 https://api.movie.example。本地调试默认 http://127.0.0.1:3000。
  • 前缀：/api/mobile/v1
  • 鉴权：当前所有接口无需登录凭证，但建议在后续版本为写操作补充签名或 token。
  • 编码：统一使用 UTF-8，所有时间戳为秒单位。

状态码约定 ​

code含义说明
0成功返回数据位于 data 字段
10001参数校验失败由全局校验管道抛出
10002找不到资源常见于视频下架或分类缺失
10003服务端错误包含数据源异常、外部接口失败等

接口如需新增非零状态码，请在后端 ErrorCode 枚举中登记，并更新本表格。

常见请求头 ​

  • User-Agent：建议携带 App 版本信息，方便后端判断兼容性。
  • X-Platform（可选）：android / ios，后端可据此做差异化配置。
  • Accept-Language（可选）：如需做多语言推荐，可在 Header 中传入。

使用说明 ​

在获取后端源码后，请先完成以下环境准备，以确保接口文档中的示例能够正常调试：

  1. 安装项目依赖：

    bash
    pnpm i

  2. 将既有数据库表映射到项目实体。项目默认不内置数据源，需要依赖 typeorm-model-generator 从现有数据库生成实体代码。

    bash
    typeorm-model-generator -h <数据库主机> -d <数据库名> -u <用户名> -x <密码> -e <数据库类型> -o <输出路径>

    常用数据库示例：

    bash
    # MySQL 示例
typeorm-model-generator -h localhost -d mydatabase -u root -x password -e mysql -o ./src/entities

# PostgreSQL 示例
typeorm-model-generator -h localhost -d mydatabase -u postgres -x password -e postgres -o ./src/entities

以上命令生成的实体文件需要与本仓库的模块结构对齐，再进行后续的数据接入与接口联调。

缓存策略 ​

  • 首页数据（/home）支持 Redis 缓存，默认键名 redisKey_homeData_{typeId}，缓存开关由 AppConfig 控制。
  • 除首页外，筛选、搜索、播放接口均为实时查询，不建议在客户端做长时间缓存。

开发者在调试时若遇到数据未更新，先确认 Redis 缓存是否仍然命中，可在后台管理的应用配置中关闭缓存。

后台配置总览（app_config 表） ​

后台管理 → APP 管理 页面将配置写入 app_config 表，不同的 type 影响如下接口：

type配置项影响接口说明
AppConfigredisStatus、redisTime、redisKey、officialUrl、officialUrlField、danmuApiUrl、playerConfigUrl所有接口；播放/弹幕/官解控制缓存策略与第三方服务地址；见各接口章节。
IndexbannerLevel、bannerLevel_<typeId>、bannerNum、hotTitle、hotLevel、hotNum、cateNum/home/type_List、/home决定首页轮播、热播与分类模块的取数策略。
CatepageNum、filter_<typeId>（含 plotFilter、areaFilter、yearFilter、languageFilter、letterFilter、sortFilter 的 status/value/title）/vod/filterList、/vod/filter/list定义筛选页的可选条件与分页大小。
SearchsearchLevel、searchNum、searchLikeLevel、searchLikeNum、searchResultLevel（字段命名取决于前端版本）/vod/search、/vod/search_recommend（若启用）配置搜索页推荐与结果加权的推荐等级/数量，详见筛选与搜索章节。
Adsstatus、bannerStatus、banner、indexCateStatus、indexCate规划中预留的首页广告位配置，当前移动端接口未消费，可按需接入。

使用配置时，请结合《页面 × 接口 × 配置映射》确认页面到配置的链路，并保持 JSON 字段与后端约定一致。