---
title: 命名约定
navTitle: 命名约定
---
# 命名约定

元数据项目中的文件名通常由资源名称和固定后缀组成。后缀决定文件类型，目录位置表达资源归属；资源的中文说明、业务描述、排序、图标等附加信息应放在资源元信息中，而不是依赖很长的文件名表达。

命名时优先考虑两件事：资源路径是否会出现在 URL 中，以及资源名是否需要和外部系统、物理表或长期引用保持一致。

## 基本规则

| 约定 | 说明 |
| --- | --- |
| 后缀固定 | `.spg`、`.dash`、`.rpt`、`.tbl` 等后缀用于匹配文件类型说明和 DTS 根结构。 |
| 同目录唯一 | 同一目录下文件名和目录名应保持唯一，避免资源引用和同步状态混淆。 |
| 名称稳定 | 项目名、应用名、文件夹名、关键数据模型名等会被长期引用，应稳定、简短、有意义，避免频繁调整。 |
| 描述进元信息 | 资源中文描述、业务口径、使用说明优先写入资源描述、`.meta` 或同名说明文件中，不把说明性长句塞进文件名。 |
| 引用字段稳定 | 文件内部的 `id`、`name`、字段名、组件名等可能被其他资源引用，重命名前要全局搜索调用方。 |

## 按资源类型命名

不同资源对名称的要求不同。常见做法如下：

| 资源 | 推荐命名 | 示例 | 说明 |
| --- | --- | --- | --- |
| 可能出现在地址栏中的资源 | 小写、短横线分隔、简短且符合 URL 习惯 | `sales-analysis`、`customer-portal` | 适用于项目名、应用名、门户模板名、`spg` 页面名、目录名等。这些资源可能被用户通过 URL 直接访问，中文描述写到资源元信息中。 |
| 数据模型 | 大写、下划线分隔、尽量不超过 32 个字符 | `SALES_ORDER`、`DIM_CUSTOMER` | 适用于 `.tbl` 等和数据库表强相关的模型。模型名建议和物理表名保持一致，表描述写到资源描述或模型说明中。 |
| 普通页面、报表和脚本 | 简短、可读、能表达用途 | `monthly-sales.rpt`、`order-detail.spg` | 面向 URL 或外部引用的资源优先使用英文小写短横线；只在内部维护的资源也应避免过长和频繁变化。 |

文件名可以使用中文，SuccApp 也能正常工作。但中文名通常表达业务含义，业务叫法变化后容易引起资源重命名、引用调整和同步冲突。对项目、应用、目录和关键模型这类基础资源，建议使用更稳定的英文或约定缩写，把中文展示名、业务说明写入元信息。

## `.meta` 资源元信息

`.meta` 是 SuccApp 克隆到本地工作目录后，在各级目录中维护的资源元信息索引文件，用来保存该目录下直接子资源的 `id`、描述、排序、图标、隐藏状态等属性。服务器上不存在名为 `.meta` 的文件；系统运行时，这些信息保存在后台数据库字段中。

新增、删除、重命名或移动本地资源时，需要同步检查相关目录 `.meta`：

1. 文件资源的元信息保存在父目录 `.meta` 中对应文件名的条目里，例如 `demo.app/.meta` 中的 `index.tpg` 条目描述 `demo.app/index.tpg`。
2. 目录资源自身的元信息保存在父目录 `.meta` 中对应目录名的条目里；目录内部 `.meta` 记录该目录自己的直接子资源。
3. 手工移动或重命名文件时，应同步更新原目录和目标目录 `.meta` 中的对应条目。

更多字段和维护规则见 [.meta 资源元信息](../file-types/config/meta.md)。

## 同名伴随文件

很多元数据资源可以带同名伴随文件。伴随文件和主资源共享同一个基础文件名，只是在主后缀后继续追加脚本、样式或说明后缀。

常见伴随文件如下：

| 伴随文件 | 用途 | 示例 |
| --- | --- | --- |
| `<资源名>.<类型>.ts`、`<资源名>.<类型>.action.ts` | 页面、报表、数据模型等资源的脚本文件，按资源类型和运行机制加载或执行。 | `order-detail.spg.ts`、`monthly-sales.rpt.ts`、`SALES_ORDER.tbl.action.ts` |
| `<资源名>.<类型>.less`、`<资源名>.<类型>.css` | 页面或资源级样式文件，按资源类型和运行机制加载。 | `order-detail.spg.less`、`sales-dashboard.dash.less` |
| `<资源名>.<类型>.md` | 资源说明文档，可描述使用场景、做法、注意事项和实现方式，也可帮助 AI agent 理解资源。 | `order-detail.spg.md`、`SALES_ORDER.tbl.md` |
| 目录资源内的 `README.md` | 目录型资源的说明文档。 | `demo.app/README.md` |

伴随文件是否会被自动加载，取决于资源类型和运行机制。例如 `page1.spg.ts`、`page1.spg.less` 是 `page1.spg` 的页面级脚本和样式；`*.spg.ts`、`*.rpt.ts`、`*.dash.ts` 等页面脚本也有对应模板；脚本模型可能使用 `*.tbl.action.ts`。不要只重命名主文件而遗漏同名伴随文件。

## 重命名和移动

重命名或移动元数据资源前，先判断操作入口：

1. 在浏览器图形化界面中重命名或移动在线资源时，系统会自动重构受影响资源中的路径引用。
2. 在 SuccApp CLI 或 SuccApp for VS Code 中直接修改本地文件名、目录名后再 push 时，系统不会替本地改动重构引用。用户或 AI agent 需要在本地同步完成引用调整，再一起提交。

本地重构时至少检查：

- 主资源文件、同名伴随文件和相关目录 `.meta` 是否一起维护。
- 旧文件名、旧路径、资源 id、组件 id、数据集 id 是否被其他资源引用。
- 页面、报表、模型、脚本、样式和说明文件中的相对路径是否仍然有效。
- 关键数据模型名是否仍和物理表、SQL、接口或外部系统约定一致。

批量重命名资源前，建议先全局搜索旧名称、文件路径、组件 id 和数据集 id，确认引用影响后再修改。