---
title: 资源引用与路径
description: >-
  说明 SuccApp Super JSON 中外部资源引用的组织方式：先在 referenceResources 建立引用列表，再在使用处引用代号，并按
  targetPath 规则保存目标路径。
navTitle: 资源引用与路径
---
# 资源引用与路径

SuccApp 元数据文件经常会用到其他资源，例如页面查询模型、按钮跳转页面、组件使用图片、程序流调用脚本、模型关联维表。外部资源引用不要散落在各个业务字段里，而是先在文件级 `referenceResources` 中建立引用列表，再由业务字段引用列表中的代号。

本文只讲外部资源引用。把另一个资源的完整内容嵌入当前文件的写法，见[内嵌资源](./inner-resources.md)。

## 外部资源先进入引用列表{#overview}

Super JSON 文件通过 `referenceResources` 统一记录外部资源引用。每个条目的 key 是当前文件内部使用的引用代号，值描述真实目标资源。

```jsonc
{
  "referenceResources": {
    "salesModel": {
      "targetPath": "$DATA:/common/FACT_SALE.tbl",
      "targetType": "METAFILE",
      "refType": "query",
      "fields": {
        "SALE_AMOUNT": "r"
      },
      "srcProperty": "sources"
    }
  }
}
```

这个结构解决两件事：

1. 让引用分析、影响分析、权限检查、重构和升级可以从一个稳定位置读取外部依赖。
2. 让业务字段不用直接保存完整路径，避免同一个目标路径在文件中重复出现。

`referenceResources` 的字段以 DTS 为准，重点查看 [`types/meta/superjson/referenceResources.d.ts`](../../../../dev-types/types/meta/superjson/referenceResources.d.ts) 中的 `ReferenceResources` 和 `ReferenceResource`。

## 使用处只保存代号{#use-ref-id}

建立引用列表以后，页面、模型、组件、动作、节点等真正使用资源的位置通常只保存引用代号。

```jsonc
{
  "sources": [
    {
      "id": "sales",
      "name": "销售明细",
      "modelType": "dwtable",
      "refType": "query",
      "path": "salesModel"
    }
  ],
  "referenceResources": {
    "salesModel": {
      "targetPath": "$DATA:/common/FACT_SALE.tbl",
      "targetType": "METAFILE",
      "refType": "query"
    }
  }
}
```

上例中，`sources[0].path` 写的是 `salesModel`，不是 `$DATA:/common/FACT_SALE.tbl`。`salesModel` 再到 `referenceResources.salesModel` 中找到真实目标。

不同文件类型的使用点字段不同。例如数据集可能用 `path`，页面样式可能用 `url(refId)`，动作或程序流节点可能用自己的目标字段。直接编辑时先看当前文件类型 DTS，再回到 `referenceResources` 确认引用代号是否存在。

代号应尽量稳定。移动或重命名目标资源时，通常只改 `targetPath`，不要顺手改代号；否则还要同步修改所有使用点字段。

## 目标路径写在 targetPath{#target-path}

`targetPath` 是外部目标资源的路径。它不是普通文件系统路径，而是 SuccApp 元数据引用路径。常见形态有四类：

1. `/` 开头：元数据绝对路径，例如 `/DEMO/data/tables/common/DIM_DATE.tbl`。
2. `.` 开头或不带 `$` 前缀：相对当前元数据文件解析，例如 `../detail.spg`、`models/order.tbl`。
3. `$XXX:` 开头：元数据引用 URI，例如 `$DATA:/common/DIM_DATE.tbl`、`$TAPP:/pages/detail.spg`、`$DB:/defdw/_def_/FACT_SALE`。
4. URL：外部链接或内联资源，例如 `https://example.com/report`、`mailto:help@example.com`、`data:image/png;base64,...`，通常配合 `targetType: "URL"` 和 `refType: "link"` 使用。

相对路径适合当前文件附近的资源。解析时以当前元数据文件为起点，`.` 开头和普通路径都会按相对路径处理；`/` 开头则直接表示元数据绝对路径。跨项目引用通常使用绝对路径。

`$DATA:`、`$ANA:`、`$FAPP:`、`$APP:`、`$TAPP:` 这类路径前缀多用于缩短同项目内的元数据文件路径。它们只是路径写法，不一定等于资源类型。例如 `$DATA:/common/FACT_SALE.tbl` 指向模型文件，`targetType` 仍应写 `METAFILE`。

完整路径规则、模块别名、资源类型路径和归一化说明见 [`types/api/succ.meta.d.ts`](../../../../dev-types/types/api/succ.meta.d.ts) 中的 `ReferenceResourcePath`。

## 类型表达引用语义{#target-type}

外部引用至少要判断两个类型字段：

| 字段 | 作用 | 主要 DTS |
| --- | --- | --- |
| `targetType` | 目标资源是什么，例如元数据文件、扩展点、数据库对象、文件数据源、主题资源。 | [`types/api/succ.meta.d.ts`](../../../../dev-types/types/api/succ.meta.d.ts) 的 `MetaResourceType` |
| `refType` | 当前文件怎么使用目标，例如查询、更新、链接、嵌入。 | [`types/metadata-meta-types.d.ts`](../../../../dev-types/types/metadata-meta-types.d.ts) 的 `MetaRefType` |

不要只按路径前缀猜 `targetType`。先判断目标本质是什么，再看同类文件和设计器保存结果。`ReferenceResource.targetType` 和 `ReferenceResource.refType` 的选择建议见 [`types/meta/superjson/referenceResources.d.ts`](../../../../dev-types/types/meta/superjson/referenceResources.d.ts)。

## 修改引用时的顺序{#editing-rules}

AI 或人工直接修改外部资源引用时，按这个顺序处理：

1. 先确认当前文件类型，打开对应文件类型 DTS，找到真正的使用点字段。
2. 判断使用点字段保存的是引用代号还是完整路径。Super JSON 中的外部资源通常应保存引用代号。
3. 在 `referenceResources` 中新增或复用同名条目。
4. 在条目里填写 `targetPath`、`targetType`、`refType`；数据资源按需填写 `fields`。
5. 移动、重命名或删除资源时，同步搜索引用代号、旧路径、文件名、组件 ID 和 `.meta` 中的伴随信息。
6. 不确定前缀、类型或字段读写关系时，优先查同类型真实文件和设计器保存后的结果。

## 内嵌资源不是外部引用{#inner-resources}

`innerResources` 看起来也通过代号使用资源，但它的含义不同：它是把另一个元数据资源的完整内容嵌入当前文件。内嵌资源不是外部资源依赖，不写 `targetPath`，也不应该作为同名条目放进当前文件的 `referenceResources`。

内嵌资源的完整说明见[内嵌资源](./inner-resources.md)。根结构定义见 [`types/meta/superjson/base.d.ts`](../../../../dev-types/types/meta/superjson/base.d.ts) 中的 `SuperJSON.innerResources`。

## 应该查看的 DTS{#dts}

| DTS | 重点查看 |
| --- | --- |
| [`types/meta/superjson/base.d.ts`](../../../../dev-types/types/meta/superjson/base.d.ts) | `SuperJSON.referenceResources`、`SuperJSON.innerResources` 的边界。 |
| [`types/meta/superjson/referenceResources.d.ts`](../../../../dev-types/types/meta/superjson/referenceResources.d.ts) | `ReferenceResources`、`ReferenceResource`，以及修改外部引用时的同步规则。 |
| [`types/api/succ.meta.d.ts`](../../../../dev-types/types/api/succ.meta.d.ts) | `ReferenceResourcePath`、`ReferenceResourceId`、`MetaResourceType`，以及路径前缀规则。 |
| [`types/metadata-meta-types.d.ts`](../../../../dev-types/types/metadata-meta-types.d.ts) | `MetaRefType`、`ReadWriteMode` 等引用用途和字段读写关系。 |
| 具体文件类型 DTS | 当前文件的业务字段如何保存引用代号。 |

## 示例和实现{#implementation}

真实写法优先查同类型元数据文件和 [`metadata-examples/DEMO/index.json`](../../../../metadata-examples/DEMO/index.json)。

需要核对实现时，看这些入口：

- 服务端：`MetaResourceType.java`、`MetaUtils.relativeReferencePath`、`MetaUtils.resolveReferencePath`、`MetaPathUtilsImpl.resolveMetaReferencePath`、`MetaRefPathResolver` 实现类。
- 前端：`relativeReferencePath`、`resolveReferencePath`、`getModuleReferencePath`。

`parseMetaRefType` 只解析原始 `$XXX:` 前缀，不能用来决定 `referenceResources.targetType`。