--- title: "开发规范" description: "QiCore 公共能力、应用代码与接口实现应遵守的工程边界。" canonical_url: "https://docs.mcent.cn/qicore/development-standards" --- # 开发规范 > QiCore 公共能力、应用代码与接口实现应遵守的工程边界。 本规范适用于 QiCore 公共模块，以及通过匹配 SDK 接入的独立应用和插件。开发时以所用 SDK kit、锁文件和宿主支持的契约为准；应用兼容范围来自实际验证。 ## 职责与依赖方向
层次 职责
QiCore 宿主 身份、会话、租户、权限、通用交易、存储、应用装配与生命周期
应用 自有业务模型、业务规则、业务页面、履约及公共能力适配器
插件 在明确所属应用与命名空间内增加已声明的能力
共享 UI 布局、组件、主题和交互
装配入口 创建共享资源、校验受信组件、连接生命周期
公共服务由宿主维护，应用通过公开 SDK 借用。应用工程不维护第二套公共登录、钱包、支付执行器或控制台外壳。新增业务不要求修改宿主注册表或基础模型。 `createApplication(serverSdk)` 是受信代码装配入口。应用和插件可以使用宿主资源，因此应来自可信交付来源；这套装配机制不提供恶意代码安全沙箱。 ## 应用工程和生成文件 下面是独立应用工程的推荐分层。QiCore 宿主源码的职责划分见[框架目录结构](https://docs.mcent.cn/qicore/introduction#%E6%A1%86%E6%9E%B6%E7%9B%AE%E5%BD%95%E7%BB%93%E6%9E%84)，两者不要求使用相同的客户端目录名。 - `apps/api`：服务端代码、模型和迁移。 - `apps/admin`：管理端页面和组件。 - `apps/miniapp`：应用自己的 H5/小程序入口与业务页面。 - `scripts`：应用自己的开发和构建入口。 - `application.json`：稳定身份和交付声明。 公共客户端源码与公共控制台层从已安装的 SDK 获取。依赖、生成目录、运行数据和正式交付物分别管理；依赖和旧构建不能作为源码复制给新应用。 具体接入顺序见[应用开发](https://docs.mcent.cn/qicore/application-development)。 ## 接口边界 普通 JSON API 使用 `/api/v1` 前缀： ```json { "data": { "items": [], "total": 0, "page": 1, "pageSize": 20 } } ``` 失败保留语义 HTTP 状态，以 `error.code`、`error.message` 表达。可用时返回的 `error.requestId` 用于排障，不是业务幂等键。文件下载、流响应与渠道通知使用各自协议。 路由入口负责解析协议、建立可信上下文并调用服务。业务校验与事务放在所属模块，输入按字段白名单、类型、长度、枚举和数值范围校验。 客户端显示错误时使用服务端公开消息；不得把 SQL、堆栈、密钥或服务器路径作为用户提示。完整协议见[HTTP 接口](https://docs.mcent.cn/qicore/http-api)。 ## 身份与权限 消费者范围是： ```text tenantId / applicationKey / userId ``` 后台账号、消费者和平台代登录分别校验。路径、查询参数和 Cookie 中的租户编号只是目标或选择提示，不能替代服务端的有效会话和范围检查。 应用权限以 `:` 限定。角色变化、应用停用、到期或插件权益撤销后，后续操作须读取当前状态；前端隐藏菜单不能替代后端鉴权。 完整范围还要进入： - 数据查询及分页计数。 - 批量操作和关联查询。 - 文件引用及下载。 - 缓存键、持久任务和幂等索引。 - 资金回调与恢复处理。 `system` 是宿主公共数据域，不是可安装的业务应用，也不替代业务应用授权。相关概念见[核心概念](https://docs.mcent.cn/qicore/concepts)。 ## 数据、事务和版本 应用模型名与物理表名使用自己的全局唯一命名空间。既有迁移不可修改、删除或换摘要；修正通过新增增量迁移完成。 金额按接口约定使用整数分，积分使用明确整数。超出 JavaScript 安全整数范围的数据按对应 DTO 使用十进制字符串等明确格式，不能用浮点计算后截断。 写操作由事务、条件更新和唯一约束共同保护。公共资产、支付事实和应用业务写入需原子提交时，使用同一个宿主事务客户端；长数据库事务内不执行外部网络请求。 配置的乐观版本、应用开通版本、钱包账户版本及资产摘要可能属于不同协议。应使用该接口读取结果中的对应字段，不能互相替代。 幂等操作固定原请求键并保存输入摘要。同键同内容返回原结果，同键不同内容报冲突。超时后先查询原结果，不能更换请求键重复扣款或重复创建任务。 日期接口保留 ISO 8601 的时区语义；业务日期按 `Asia/Shanghai` 处理，完整时间显示到秒。界面不额外重复时区提醒。 ## 共享 UI 与动作状态 管理端继承 SDK 的 Console 层，复用现有组件和租户上下文： - 保存使用 `ConsoleFormActions`。 - 抽屉使用 `ConsoleDrawer`。 - 放弃修改使用 `ConsoleDiscardChangesDialog` / `useDiscardChanges`。 - 查询、重置、刷新、保存和行操作分别持有自己的加载状态。 - 保存后重载和后台刷新不点亮用户主动搜索或刷新按钮。 站点或账号变化后，旧请求不得覆盖新上下文。成功、失败、取消及并发请求都要正确结束所属动作。 首个 HTML 就返回当前路由的最终标题和 favicon。直接访问、刷新与站内导航都要验证，不能靠挂载后的改标题、定时器或空白标题过渡。 ## 文件与渠道 文件通过宿主绑定应用身份的存储接口管理，业务代码不把磁盘绝对路径当作公共文件引用。平台统一存储也不意味着不同租户、应用或用户共用可见性。 图片、上传、外部 URL 和渠道调用继续使用宿主现有校验、资源限制、凭据修订与审计。密钥只返回配置状态；日志和示例不包含真实秘密。 客户端播放广告完成、支付面板成功或页面跳转成功均是客户端事件。业务权益和资金结果仍由所属服务端协议确认。 ## 交付前的必要检查 1. 对所用 SDK kit、应用描述、入口、权限和路由进行契约验证。 2. 检查不同租户、应用及用户之间的读取和写入隔离。 3. 验证撤权、冲突、重复请求、未知网络结果和重启恢复。 4. 在隔离数据库验证模型和迁移，保留业务数据与恢复记录。 5. 验证直接访问、刷新、导航以及受影响操作的延迟响应。 6. 在匹配的 Linux 环境生成完整运行包；H5、小程序和真实渠道按各自范围验证。 7. 分别记录本地验证、发行材料准备、发布和部署状态。 继续阅读[开发工作区](https://docs.mcent.cn/qicore/development-workspace)、[服务端 SDK](https://docs.mcent.cn/qicore/server-sdk)或[生命周期与打包](https://docs.mcent.cn/qicore/lifecycle-and-packaging)。 ## Sitemap See the full [sitemap](https://docs.mcent.cn/sitemap.md) for all pages.