PHP 门户接后端接口，字段为什么总是静默丢失？4 个固定动作 + 6 个静默踩坑点

connor

"我加了字段，为什么保存之后还是空的？"
这是我最常收到的问题之一。通常伴随着这样的画面：改了 PHP、也改了后端、控制台没报错、接口返回 200，但页面上那个字段就是空的。
答案往往是：你只改了两处，第三处漏了。
更麻烦的是"本地好好的，部署上去就 403"——这个坑更反直觉，它能让人排查一整天。
这篇讲 PHP 门户怎么接后端接口：门户的定位、四个固定动作、三条视图铁律，以及那个 403 之谜的真正原因。范例来自真实代码：/portal/stores（店铺管理页），对应 PortalController::adminStores() + views/admin_stores.php。
一、先搞清楚门户的定位

PHP 门户不是业务层，它是「透传层 + 视图层」。
这意味着：

• ❌ 不要在 PHP 里写业务规则（不要在门户算佣金、算折扣、判断库存）
• ✅ PHP 只做三件事：拿会话 token、调后端 API、把数据渲染成 HTML
  

为什么这么设计？ 因为同一套后端要同时服务 B/S 门户、小程序、开放 API、企微。规则放在 PHP 里，小程序就得重写一遍。
这句话的代价是你要多改一个地方——加字段时 PHP 的转发链也得改。但收益是规则只有一份，四端行为永远一致。
对快消分销这种四端一体的系统，这个取舍是必须的：你没法让运营去跟开发说"小程序上的佣金算法跟后台不一样"。
二、门户的四个组成部分

请求打到门户的 /api/stores，index.php 里没匹配到显式路由，落到通用透传分支，proxyApi() 再转给后端。
前端发了一个 storeId，后端不认，就当它不存在。没有 unknown field 警告，没有 400，就是静默丢弃。
这也是为什么"字段静默丢失"这三个字要强调。任何会静默丢弃输入的校验逻辑，都是这种 bug 的温床。 好一点的实现会在 normalize() 里检测未识别的字段并告警——那样这个 bug 在开发第一天就暴露了。
所以现在回过头看 createProductAction() 里那句 // 所属店铺（空 = 平台自营）——它不是注释，是给未来的自己的警告。
五、两个绕不开的机制

5.1 apiCall() 的 401 自动重登

第 3 点里的"路径前缀决定是否免登录"是个约定与实现耦合的典型例子：白名单是靠路径前缀判断的，所以你的路由命名不是随意的——/u/ 和 /agent 已经被占了，别的公开页面得另想办法。
第 1 点（门户权限 = 管理员权限）是这套设计的结构性代价。因为门户是个内部工具，没有做多角色，所以它的 token 就是 admin。这意味着任何能访问门户 URL 的人，都是管理员。所以门户必须严格地挡在登录后面，而且那个登录不能和后端 admin 共用凭据。
六、demo 版的 403 之谜

这个坑值得单独开一节，因为它排查起来很反直觉。
现象：本地开发时新增的 /api/xxx 接口一切正常，部署到展示站后返回 403，index.php 里明明没这个限制。
视图文件不存在时会 fallback 到 placeholder.php —— 写错视图名不会报错，只会显示占位页。这个"贴心"设计反而容易让人以为是数据问题。
这个 fallback 是典型的为了不崩而牺牲可观测性。但你只要记住"页面显示成一个空白占位框 = 视图文件名写错了或路径不对"，5 秒钟就能定位。前提是你知道有这回事——这就是它反直觉的地方。
主题配色通过 $theme 注入到 layout，二开做品牌定制时改 frontend/ 的 CSS 变量即可，不用动 PHP。
八、本篇 checklist

加一个管理页面，按顺序走：

• index.php 的 GET 路由表加了页面路由
• index.php 的 POST 路由表加了表单 Action（如有）
• PortalController 加了对应方法，ensureToken() + apiCall() + render()
• views/xxx.php 写好了，所有输出 htmlspecialchars()
• config.php 的 nav_items 加了入口，选对 edition
• 表单新字段三处都改了（后端 normalize / 门户 Action / 前端表单）
• 如果是 demo 站也要用的 /api/* 接口，确认已显式注册
• rebuild 了 php-portal 镜像（docker compose up -d --build php-portal）
  

最后一条是个纯粹的部署形态问题：php-portal 的代码是 COPY 进镜像的，不是 volume 挂载。所以你改了本地文件，容器里的还是旧的。改完不 rebuild，你会看到自己刚写的代码"没有生效"——而且因为文件确实存在于宿主机，你很难往那个方向想。
总结

接后端接口这件事，技术难度不高，但坑的密度不低。这篇拆开的 6 个静默踩坑点：
#坑表现根因
1字段静默丢失接口 200，字段永远空门户 Action 没转发，后端 normalize() 静默丢弃
2demo 版 403本地正常，展示站 403依赖通用透传，而 demo 版禁透传
3引号截断 XSS单引号数据破坏 onclickjson_encode 没加 JSON_HEX_APOS
4缺 ?? '' 白屏后端加字段后页面 500取值没默认值
5__status 被吃业务字段凭空消失与 apiCall 的内部约定撞名
6不 rebuild 不生效改了代码页面没变php-portal 是 COPY 进镜像，不是 volume前两个坑已经被单独开节讲透了（第 4、6 节），后面四个散落在正文里。
归纳成三句话：
**门户是透传层 + 视图层，不是业务层。**所以加字段要改三处，漏了中间那处就是"静默丢失"——因为后端的 normalize() 会宽容地丢弃它不认识的字段。
**demo 版禁透传。**任何要在展示站用的 /api/* 接口，必须在 $routes 里显式注册。隐式行为在切换环境时就会变成显式故障。
**权限是继承来的，不是声明的。**门户用 admin 身份调后端，意味着门户的每个用户都是管理员——所以门户必须挡在登录后面，而且那个登录不该和后端 admin 共用凭据。
真正要带走的，其实是**"静默"这两个字**。上面 6 个坑的共同点不是难，而是它们都不给你任何信号——不报错、不告警、不中断。所以每加一个字段，就把这三处都过一遍；每改一次 PHP，就 rebuild 一次。