v1.13.0:开放 API,把内容以只读 JSON 接口对外开放

发布时间:2026-11-13 浏览:21 栏目:卫民CMS

2026 年 11 月 13 日,卫民CMS 演示站交付 v1.13.0。这一版加的是开放 API:站点信息、新闻列表与详情、产品、单页、栏目、导航菜单、版本日志,都可以用标准 HTTP 请求拿到干净的 JSON。前台视觉、主 CSS 与 Logo 照旧不动。

为什么一个演示站要做开放 API

判断一套 CMS 是不是真的,有个很直接的办法:看它能不能把自己的数据干干净净地交出去。页面能看,说明模板层能用;接口能取,说明表结构、发布状态、多站点隔离、权限边界这些底层的东西都是真的,而不是页面里写死的文案。所以这一版不是「跟风加接口」,而是把「内容已经结构化」这件事变成一个可以被外部验证的事实。

另一个现实原因是交付:客户后续要对接小程序、要接企业微信、要把新闻同步到别的平台,如果每次都要改模板或写一次性脚本,说明系统还停在「会渲染页面」的阶段。有了一套稳定的只读接口,这类需求就从开发变成了配置。

设计取舍一:只做读,不做写

开放写接口的门槛比读高一个量级:要防重放、要防越权、要处理并发冲突、要考虑幂等。演示站对外公开、账号是公开的,把写能力放出去等于给自己挖坑。所以这一版明确只提供只读接口,写操作仍然只在后台、只走带 CSRF 令牌的 POST 表单。

接口分成两级。第一级是公开只读,路径前缀 /api/v1/open/,不需要任何凭据,适合演示与轻量嵌入;第二级需要 Authorization: Bearer <token>,路径是 /api/v1/,给正式对接用,可单独停用、重置、限速。两级共用同一批控制器逻辑,只是入口鉴权不同,避免两套代码慢慢跑偏。

设计取舍二:令牌只存摘要,日志不记内容

令牌表 wm_api_token 里没有明文令牌这一列 —— 只存 8 位前缀和 SHA-256 摘要。明文在创建或重置的那一刻生成,写进 Session 闪存,跳到列表页显示一次,刷新即消失。这样即使数据库被导出,也拿不到可用的令牌;后台能看到的只是「前缀 + 创建时间 + 最后使用时间 + 状态」。

调用日志 wm_api_log 同理克制:只记方法、路径(不含查询串)、状态码、耗时、令牌 ID 和 IP 的哈希。不记请求体、不记 Header、不记明文 IP —— IP 用 sha256(ip + 固定盐) 存,既能统计异常来源,又不构成一份访问者档案。日志表故意不挂静态缓存失效钩子,写日志不该引起整页缓存重建。

响应字段一律走白名单 field(),不做 toArray() 全字段输出。账号、留言、站点配置这些不该出现在公开接口里的表,一个字段都不出去。所有查询固定三个条件:status=1 + 当前 site_id + delete_time=0(个别表没有软删除列,就按实际列写)。回收站里的内容与未发布的草稿,永远不会通过接口泄露。

坑一:路由没命中不等于 404

接口上线第一天就遇到这个问题:请求一个不存在的端点,返回的不是 JSON 404,而是首页的 HTML。原因是 ThinkPHP 的路由是旁路 —— 路由表没命中时,会回落到默认调度,把 PATH_INFO 第一段当控制器、第二段当方法去找。找不到控制器才抛异常,于是最终表现成一个 500 或者被异常处理页接走。

解法是在 API 路由文件末尾显式写 Route::miss(),指向一个只回 JSON 的错误控制器,固定返回 {"code":4040,"message":"接口不存在","data":null} 与 HTTP 404。同时 route_complete_match 保持开启,避免前缀模糊匹配把 /v1/articles/xxx 误配到列表方法上。

坑二:401 被改写成 500

令牌校验失败时控制器抛 HttpResponseException,携带 401 响应。但全局异常处理在 API 分支里对「所有异常」统一渲染 500,把这个已经准备好的响应又包了一层 —— 客户端拿到的状态码是 500,提示是「服务暂时不可用」,完全误导排查方向。

HttpResponseException 是框架用来「携带一个现成响应往上抛」的机制,后台的 302 回退也靠它。所以异常处理的第一行必须是放行:命中就直接返回它带的响应,只额外补一个 X-Static-Cache: SKIP 头,然后才轮到其它分支。改完 401 的四种状态(无令牌、无效令牌、已停用、正常)才全部符合预期。

坑三:API 的报错不在主日志里

某个公开端点一直 500,主日志 runtime/log/ 里却一条 error 都没有,只能靠猜。原因是多应用扩展会改写应用的运行时目录,API 作为独立应用,日志落在 runtime/api/log/。这和之前静态缓存 Web/CLI 目录分裂是同一类坑:排查时先确认「日志到底写在哪」,比反复看代码有效。

顺带暴露的真问题是漏了一个 use:控制器里用了 SiteContext::id() 却没导入,PHP 把它当当前命名空间下的类去找,直接 class not found。补上导入即恢复。

坑四:nginx 的伪静态把 /api/ 抢走了

这一版最长的一段排查在 nginx。目标很清楚:/api/ 用独立的限流区(30 次/分钟,突发 10),PHP 返回的 404 不要被网关替换成默认错误页,429 也要回 JSON。配置写完 nginx -t 通过、reload 成功,但实测 16 次连发全部 200,限流完全没生效,404 还是 HTML。

根因是伪静态规则的位置:它写在 server 级的 if (!-e $request_filename) { rewrite ... last; } 里。nginx 的 server 级 rewrite 在 location 匹配之前执行,/api/v1/site 在这一步就被改写成 /index.php?s=/api/v1/site,后面那个 location ^~ /api/ 永远轮不到 —— 限流、fastcgi_intercept_errors off、PATH_INFO 参数全部落空。

修法是把伪静态包进 location / { if (!-e $request_filename) { rewrite ... last; } },让 /api/ 前缀被更精确的 location 先截走。改完 16 次连发变成 10 个 200 加 6 个 429,404 也回 JSON 了。

还有一个次要坑:全局开了 fastcgi_intercept_errors on,PHP 返回的 404 响应体会被 nginx 的默认错误页替换(401/403/429 不受影响)。所以 /api/ 的 location 里必须显式关掉它。网关层的 429 则用 error_page 429 /429.json 指向一个静态 JSON 文件,保证「被限流」也是接口能解析的格式。

坑五:静态缓存要显式排除,不能靠巧合

整页静态缓存中间件挂在全局管道里,排在 Session 初始化之前。API 的响应是 application/json,看起来「不是 HTML 所以不会被写盘」,但中间件的 before 仍然会去读一次缓存文件。这种依赖格式巧合的行为不能留 —— 万一哪天有人加了一个返回 HTML 的调试端点,就会被缓存住。

所以在判后台的同一层加了 API 判定(REQUEST_URI 以 /api/ 开头,或 pathinfo 首段是 api),命中就直接放行并显式回 X-Static-Cache: SKIP。排除项必须显式回 SKIP,否则「按设计排除」和「中间件没加载」的响应完全一样,出问题时无法区分。模板主题中间件同样跳过 API,避免把前台主题的模板路径注入到接口请求里。

后台一侧:令牌管理与调用日志

后台新增两个入口。「开放 API」管令牌:创建(填名称与备注)、启停、重置、删除;重置会生成新明文并让旧令牌立即失效。「调用日志」是只读列表,可按令牌筛选,公开版请求的令牌 ID 记为 0 并显示为「公开版」。两个模块都纳入角色权限(api.view / api.write),并进演示账号的只读保护 —— 演示账号可以看,不能重置令牌。

令牌的速率上限在入库时钳在合理区间(默认 50 次/分钟,公开版 10 次/分钟),避免误填一个极大值把网关限流架空。网关限流与令牌限流是两层:网关按 IP 兜底防刷,令牌按凭据做配额,两者互不替代。

文档页:还是复用同一个模板

接口说明页放在 /open-api.html。这里有个命名约束:不能叫 /api.html,会和应用名冲突,请求可能被当成 API 应用的路由。内容上给了两种访问方式的对照、九个端点的清单、统一响应结构与错误码表,示例响应直接用线上真实数据生成(最新一篇新闻、产品数量),不写假数据。

页面复用了已有的 page/index.html 模板,不新增模板文件,样式写在内容块内的 <style> 里。原因和上一版一样:主题机制要求默认主题与现有模板逐字节一致,少一个模板文件,升级时就少一处同步。说明页同时登记进 sitemap 与静态构建的 URL 清单,构建页数从 24 变成 25。

验收结果

公开端点七个全部 JSON 200;不存在的端点返回 JSON 404 且带 X-Static-Cache: SKIP。令牌认证四种状态符合设计:无令牌 401、无效 401、有效 200、停用 401。令牌全生命周期实测一遍:创建后立即可用、速率被钳到上限、停用后立刻 401、删除后表内归零。限流连发 16 次得到 10 个 200 与 6 个 429,网关层 429 也是 JSON;后台的登录限流口径未受影响。调用日志确认路径不含查询串、IP 为哈希、公开版令牌 ID 为 0。静态页生成成功 25 / 失败 0,前台 15 个地址全部 200,首页仍命中缓存,后台各入口正常。主 CSS 未改动。

改动范围

新增 app/api 独立应用(路由、基类、八个资源控制器、未命中兜底);新增 wm_api_token 与 wm_api_log 两张表及回滚 SQL;新增两个模型、后台两个控制器与三个模板、两个权限点与菜单入口;新增前台说明页并在 sitemap 与静态构建中登记;静态缓存与主题中间件增加 API 排除分支;异常处理增加 API 分支并放行 HttpResponseException;nginx 增加独立限流区、/api/ location 与网关 429 的 JSON 响应;伪静态规则从 server 级改为 location 内。前台视觉、主 CSS、Logo 均不在本批改动内。