---
title: "应用开发"
description: "从匹配的 SDK kit 开始，在独立工程中开发、联调和交付 QiCore 应用。"
canonical_url: "https://docs.mcent.cn/qicore/application-development"
---
# 应用开发

> 从匹配的 SDK kit 开始，在独立工程中开发、联调和交付 QiCore 应用。

应用是独立的业务交付单元。开发者维护自己的源码、版本、模型、迁移和各端产物，通过 SDK 与 QiCore 的受信装配契约使用公共能力。

本文中的 `notes-app` 是示例业务标识，`app_notes_demo` 是示例包标识。它们不代表已登记、已授权或可直接安装的真实产品。

## 从哪里开始

<table>
<thead>
  <tr>
    <th>
      步骤
    </th>
    
    <th>
      要完成的内容
    </th>
    
    <th>
      详细文档
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      1
    </td>
    
    <td>
      取得匹配的 SDK kit，声明精确版本并安装依赖
    </td>
    
    <td>
      <a href="https://docs.mcent.cn/qicore/development-workspace">
        独立开发环境
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      2
    </td>
    
    <td>
      声明应用身份、可选界面和持久任务
    </td>
    
    <td>
      <a href="https://docs.mcent.cn/qicore/application-manifest">
        应用描述与运行时
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      3
    </td>
    
    <td>
      通过宿主注入的公共 API 实现服务端逻辑
    </td>
    
    <td>
      <a href="https://docs.mcent.cn/qicore/server-sdk">
        服务端 SDK
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      4
    </td>
    
    <td>
      复用控制台层和公共客户端能力
    </td>
    
    <td>
      <a href="https://docs.mcent.cn/qicore/console-sdk">
        控制台接入
      </a>
      
      、<a href="https://docs.mcent.cn/qicore/client-sdk">
        客户端接入
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      5
    </td>
    
    <td>
      验证跨租户隔离、模型迁移和故障恢复
    </td>
    
    <td>
      <a href="https://docs.mcent.cn/qicore/storage-and-transactions">
        存储与事务
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      6
    </td>
    
    <td>
      独立构建完整包，执行描述与文件布局校验
    </td>
    
    <td>
      <a href="https://docs.mcent.cn/qicore/lifecycle-and-packaging">
        生命周期与打包
      </a>
    </td>
  </tr>
</tbody>
</table>

SDK 提供开发 CLI 和最小服务端包模板。业务目录、业务页面和构建脚本由应用工程维护，按实际功能实现后再声明对应能力。

## 应用开发工程推荐结构

下图按服务端、控制台和客户端分层，供独立应用组织源码。标记“可选”的部分只在应用需要时维护：

```text
notes-application/
├─ package.json                  必需：依赖、脚本、qicore.sdk 和开发入口声明
├─ pnpm-lock.yaml                必需：锁定当前应用依赖与 SDK 档案
├─ application.json              必需：应用身份、版本及产物声明
├─ apps/
│  ├─ api/
│  │  ├─ src/                   业务服务、适配器及服务端入口源码
│  │  └─ prisma/                可选：应用自有模型和不可变增量迁移
│  ├─ admin/                    可选：独立 Nuxt 控制台工程
│  │  ├─ nuxt.config.ts         继承 SDK Console 层
│  │  └─ app/pages/tenant/      应用自己的后台页面
│  └─ miniapp/                  可选：H5／小程序工程与业务资源
├─ scripts/
│  ├─ development.mjs           本例开发入口，接收 server/admin/h5 模式
│  └─ ...                       应用自己的各端构建和打包脚本
└─ .local/qicore-sdk/            kit 安装的当前 SDK 档案，忽略且不入发行包
```

`apps/api`、`apps/admin` 和 `apps/miniapp` 是推荐分层，不是宿主强制扫描的目录名。宿主读取根 `application.json`，并通过 `package.json` 的 `qicore.development.entry` 调用应用自己的开发脚本。

本例将该入口放在 `scripts/development.mjs`；构建由它将源码转换为宿主要求的输出。具体模式和输出位置见[独立开发环境](https://docs.mcent.cn/qicore/development-workspace)。仅有上面的文件夹不会自动完成应用接入。

公共登录、租户隔离、钱包、支付网关和 Console 外壳由框架维护。应用只依赖已安装的 SDK 包，不复制宿主实现，不编辑宿主注册表来安装自己的业务。

## SDK 实际提供的最小模板

安装 SDK 后，可通过 `@qicore/application-sdk/templates/application-package/*` 定位已有模板；其实际结构是：

```text
application-package/
├─ application.json              最小服务端应用描述
├─ entry.mjs                     导出 createApplication(serverSdk)
└─ README.md                     模板使用说明
```

模板中的 `entry.mjs` 返回应用定义和 `createRuntime(resources)` 工厂，并提供必需的生命周期方法。它没有业务表、后台页面、客户端工程或真实发行材料。

开发 CLI 用于将已有应用接入显式选择的宿主，不会生成上面的完整业务工程。开发者实现业务和构建脚本后，再按实际产物增加描述。入口字段见[应用描述与运行时](https://docs.mcent.cn/qicore/application-manifest)。

## 构建后的发行包结构

发行包保存可运行产物，与开发源码目录分开：

```text
应用包根/
├─ application.json              必需：与服务端定义一致的应用描述
├─ release-manifest.json         必需：真实文件、版本、兼容与迁移清单
├─ entry.mjs                     必需的服务端入口示例，新包推荐名称
├─ migrations/                   可选：有增量迁移时提供
│  └─ YYYYMMDDHHmmss_create_notes.sql
├─ node_modules/                 可选：应用确有需要的生产运行依赖
└─ web/                          可选：只保留实际声明的端
   ├─ admin/
   │  ├─ server/index.mjs         声明后台时必需的 SSR 入口
   │  └─ public/                 后台公开资源的固定位置
   ├─ h5/
   │  ├─ index.html              声明 H5 时必需
   │  └─ h5-routes.json          声明 H5 时必需
   └─ mini-program/
      └─ mini-program-template.json  声明小程序时必需的模板清单
```

服务端实际入口以发行清单的 `entrypoint` 为准，不为统一名称改写已有合法包。各 `web` 端的位置由描述契约固定；没有提供某端就不声明，也不创建占位产物。

`release-manifest.json` 来自真实文件扫描和发行流程，不由 SDK 最小模板预置。开发源码、开发依赖、测试、缓存、环境文件、实例数据和授权材料不进入运行包。完整校验与生命周期见[生命周期与打包](https://docs.mcent.cn/qicore/lifecycle-and-packaging)。

## 选择开发方式

应用开发者在应用工程内执行已安装 SDK 的 CLI，显式选择官方宿主：

```bash
pnpm dev --host /path/to/official-qicore --state /path/to/private-dev-state --port 4300
pnpm dev:stop --host /path/to/official-qicore --state /path/to/private-dev-state
```

这里假定应用的 `scripts.dev` 和 `scripts.dev:stop` 已按[独立开发环境](https://docs.mcent.cn/qicore/development-workspace)声明。此方式使用应用锁定的已安装 SDK。

参与 QiCore 公共能力开发时，在宿主工程内显式加载应用源码：

```bash
pnpm dev --app /path/to/notes-application
pnpm dev --app /path/to/application-a --app /path/to/application-b
pnpm dev:stop
```

此方式默认使用源码 SDK，便于联调公共能力。两种模式都不要求宿主与应用目录相邻。

## 从宿主借用资源

应用入口导出 `createApplication(serverSdk)`，返回定义和运行时工厂。运行时通过 `createRuntime(resources)` 获得宿主管理的数据库，以及已经绑定当前应用身份的存储接口。

- 公共服务借用同一个宿主实例，业务写入使用受控事务。
- 消费者数据完整限定 `tenantId/applicationKey/userId`。
- 运行时只释放自己创建的 watcher、连接和任务资源，不关闭宿主数据库。
- 应用声明与服务端入口的 `key`、`packageKey`、`name` 和 `version` 必须一致。
- 当前应用模型适配要求 Prisma `6.19.3`；SDK API 兼容不等于模型适配兼容。

具体方法、身份前置和事务边界见[服务端 SDK](https://docs.mcent.cn/qicore/server-sdk)。

## 按实际能力接入

先实现可验证的业务链路，再增加页面、模型或公共能力适配器。没有提供后台、H5 或小程序产物时，不在 `web` 中声明该端；没有持久任务时显式填写 `pendingTasks: []`。

同一平台可以装配多个应用，一个租户最多选择一个当前应用，也可以暂不选择。开发装配仍会核验身份、权限、模型和路由冲突，不能把本地目录选择当成租户授权。

## 交付前的判断

应用应能在只安装匹配 SDK kit 和自身依赖的干净目录完成构建，离开原开发目录后不借用相邻工程的依赖或私有配置。

本地开发装配证明开发链路可用；完整包校验、正式发行材料、实例安装和真实渠道联调分别完成。面向客户交付的是已构建的匹配运行产物，不要求客户安装源码依赖或现场编译。


## Sitemap

See the full [sitemap](https://docs.mcent.cn/sitemap.md) for all pages.