中国 帮助

C 端接口与应用

这是接入 PC 用户端(以及 H5 / App)时最容易踩的坑,值得单独一页。 一句话 业务性的 C 端控制器都在应用(插件)里。 /open/mall/、/portal/member/、/site/shop 这些路径由对应应用提供;

C 端接口与应用
封面

> 本文整理自平台文档 docs/wujies/5.x/frontends/pc/open-api.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-9ae47c64982b-cover.svg)

这是接入 PC 用户端(以及 H5 / App)时最容易踩的坑,值得单独一页。

一句话

业务性的 C 端控制器都在应用(插件)里。 /open/mall/、/portal/member/、/site/shop 这些路径由对应应用提供;应用没安装,接口就是 404。宿主只留平台能力:/auth/、/system/、/app/**,以及少数几个跨应用接口(/portal/user 个人资料、/open/system/message 消息、/open/{code}/config 站点配置)。

为什么要这样设计

如果 C 端接口写在宿主里,那么每加一个 C 端业务(商城、会员、考试……)都要改宿主、重新编译、重新发版。把 C 端能力随应用走之后:

  • 加一个业务 = 装一个应用;
  • 应用可以独立升级,不需要重启宿主;
  • 用户端只依赖「接口契约」,不依赖「平台版本」。

代价是:接口是否存在,取决于运行期装了哪些应用。 这正是排查时最容易忽略的变量。

排查顺序

接口 404
  ├─ ① 对应应用装了吗?启用了吗?   → 我的应用 / 应用市场
  ├─ ② 应用版本包含这个接口吗?     → 应用详情里的版本与更新日志
  └─ ③ 最后才查路径拼写 / 代理配置

不要一上来就查 Nginx 和前端代码。先确认应用装没装,能省掉大部分时间。

在后台「我的应用」里看应用状态;或直接请求后端 GET /app/runtime/enabled-apps,它只要求登录、不校验权限,返回本租户已启用的 appCode 列表(如 ["member","mall"]),前端就靠它决定要不要发这个请求。 后台侧另有 GET /app/install/mine(信息更全,但要 app:install:list 权限,C 端 token 拿到的是 403,不是没装)。

常见接口前缀

前缀典型用途提供方
/open/**无需登录的开放数据(商品、内容、配置)业务应用;/open/system/message、/open/{code}/config 是宿主
/portal/**登录用户的门户数据(订单、会员、关注、评论)业务应用;/portal/user 是宿主
/site/**面向匿名访客与搜索引擎的整页 HTML(首页、商品、店铺、图床、企业、考试、询价…),主题资源走 /site/themes、/site/apps/**业务应用直接渲染,不是给 SPA 用的 JSON 接口
/auth/**登录、注册、验证码、刷新 token平台宿主
/system/**字典、地区、用户信息、菜单等基础能力平台宿主
/app/**应用安装与运行期清单平台宿主(应用市场模块)

具体路径以各应用的接口清单为准,见 [HTTP 接口索引](/docs/wujies/5.x/platform/reference/api) 与 [开放接口清单](/docs/wujies/5.x/platform/open-api/endpoints)。

登录与 token

  • 两端是同一套登录体系:都 POST /auth/login,都带 VITE_APP_CLIENT_ID(同一份配置,对应 sys_client 里的 pc 那行)与 clientid 请求头,Authorization: Bearer <token>;
  • token 键名也相同(Admin-Token),所以同域生产部署时后台与用户端共用一次登录;开发态端口不同(后台 80、用户端 4230、后端 8086),origin 不同,localStorage 互相看不见;
  • 后端直出的 /site/ 页面不读 localStorage(按 origin 隔离),它看的是后台登录时写的 wujies-site-state 标记 cookie——只表示"这台浏览器登录过",不含任何凭据**,平台关掉了 cookie 鉴权(is-read-cookie: false)以免开 CSRF 的口子;
  • 401 时跳登录页;403 是权限不足,不要当成未登录处理。

跨域

开发环境走 Vite 代理,不存在跨域;生产环境两种做法:

1. 同域反代(推荐):VITE_APP_BASE_API=/prod-api,Nginx 转发到后端,顺带让 /site/ 与 SPA 同源; 2. 跨域直连**:VITE_APP_BASE_API 填后端公网地址(当前仓库里是 https://api.wujies.cn/),后端必须允许对应 Origin、Credentials 与自定义头(clientid)。

改了 .env.production 要重新构建,环境变量是构建期注入的。

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-9ae47c64982b-guide.svg)

章节导览
THE END

喜欢就支持以下吧

评论区需要浏览器启用 JavaScript 才能加载。

回到内容