---
title: 根据需求判断文件类型
description: 说明新建或维护元数据文件时，如何从需求出发选择文件大类、具体文件类型和存放位置。
navTitle: 判断文件类型
---
# 根据需求判断文件类型

新建或维护元数据文件时，先不要从后缀开始猜。更稳妥的方式是先看要解决的需求，确定文件大类，再选择具体文件类型，并按该类型的目录约定放到合适位置。

SuccApp 元数据文件不只包括 JSON，也包括 `.js`、`.ts`、`.less`、`.css`、`.png` 等脚本、样式和静态资源。同样是 JSON，不同后缀、约定文件名和存放位置也可能对应不同的格式规范。

## 先判断需求大类{#category}

| 需求大类 | 适用需求 | 常见文件类型 | 详细说明 |
| --- | --- | --- | --- |
| 数据与模型 | 维护业务对象、数据模型、复用查询、知识库内容 | `.tbl`、`.query`、`.kdb` | [数据与模型文件类型](../file-types/data/README.md) |
| 页面与应用 | 搭建应用边界、业务页面、模板页面、报表填报应用、前端脚本和样式 | `.app`、`.spg`、`.tpg`、`.fapp`、`.ts`、`.js`、`.less`、`.css` | [页面与应用文件类型](../file-types/views/README.md) |
| 报表与可视化 | 搭建仪表板、报表、主题和可视化分析页面 | `.dash`、`.rpt`、`.theme` | [报表与可视化文件类型](../file-types/ana/README.md) |
| 后端流程与控制 | 编排程序流、工作流、自定义接口、后端脚本和系统事件逻辑 | `.afl`、`.wfl`、`.action.ts`、`.action` | [后端流程与控制文件类型](../file-types/backend/README.md) |
| 配置与元信息 | 配置数据源、系统设置、项目设置、应用设置和资源元信息 | `.jdbc`、`settings.json`、`.meta` | [配置与元信息文件类型](../file-types/config/README.md) |
| 静态资源 | 维护图片、字体、附件、压缩包和主题素材 | 图片、字体、附件、压缩包等 | [资源文件](../file-types/assets/README.md) |

## 再选择具体文件类型{#file-type}

确定大类后，继续根据文件要承担的职责选择具体类型。例如：

1. 需要定义业务对象、字段和分析口径时，通常使用 `.tbl`。
2. 需要复用一段稳定取数逻辑时，通常使用 `.query`。
3. 需要搭建通用交互页面时，通常使用 `.spg`；需要搭建仪表板或报表时，分别使用 `.dash`、`.rpt`。
4. 需要编排服务器端业务动作时，通常使用 `.afl`；需要人工审批和任务流转时，使用 `.wfl`。
5. 需要编写后端自定义逻辑时，优先使用 `.action.ts`；需要编写页面前端逻辑时，优先使用 `.ts`。
6. 需要调整系统、项目或应用配置时，先判断是系统设置、项目设置、应用设置还是数据源连接，不要只按 `settings.json` 处理。

如果当前项目中已经有同类资源，优先参考同目录同类文件的组织方式、命名方式和字段顺序。

## 确认存放位置{#location}

文件类型决定文件格式，存放位置决定作用范围。选择类型后，再确认文件应该放在哪个项目、应用或目录中：

1. 普通业务资源通常放在对应元数据项目中。
2. 系统级设置、系统数据源、内置应用和全局资源通常放在 `sysdata`。
3. 只服务某个低代码应用的页面、脚本、配置和素材，优先放在对应 `.app` 应用目录中。
4. 项目级配置通常放在项目的 `settings/` 目录中。
5. 图片、字体、附件等静态资源应放在被引用方能稳定访问的位置，并同步检查引用路径和 `.meta`。

具体目录以对应文件类型页和当前项目已有结构为准。遇到存放位置不确定的文件，先阅读[元数据项目](./project.md)和[文件新建和修改规范](./file-editing-rules.md)。

## 学习格式规范{#format}

确定文件类型和位置后，再进入对应文件类型页了解格式规范、DTS 入口、常见位置和编辑注意事项：

1. SuccApp Super JSON 类文件先读[SuccApp Super JSON](./super-json.md)，再结合对应文件类型页和 DTS 确认字段结构。
2. 后端脚本先读 [.action.ts 后端脚本文件](../file-types/backend/action-ts.md)，再查看[后端脚本 API 索引](../../script/backend/api-index.md)。
3. 前端脚本、样式和静态资源按对应语言、编译产物、加载机制和引用路径规则维护。
4. `.meta` 按 [.meta 资源元信息](../file-types/config/meta.md) 维护，不要把它当成业务文件内容本身。

完整文件类型索引见[文件类型概述](../file-types/overview.md)。