元数据标签

元数据标签 {#metadata-tags}

随着项目规模和复杂性的增长，一次性处理整个代码库可能会变得效率低下。Tuist 提供元数据标签作为将目标组织成逻辑组并在开发过程中专注于项目特定部分的方式。

什么是元数据标签？ {#what-are-metadata-tags}

你可以附加到项目中目标的字符串标签。它们作为标记，允许你：

对相关目标进行分组 - 标记属于同一功能、团队或架构层的目标
聚焦你的工作空间 - 生成仅包含具有特定标签的目标的项目
优化你的工作流程 - 处理特定功能，而无需加载代码库的不相关部分
选择要保留为源码的目标组 - 选择在缓存时你希望保留为源码的目标组

标签使用目标的 metadata 属性定义，存储为字符串数组。

定义元数据标签 {#defining-metadata-tags}

你可以将标签添加到项目清单中的任何目标：

import ProjectDescription

let project = Project(
    name: "MyApp",
    targets: [
        .target(
            name: "Authentication",
            destinations: .iOS,
            product: .framework,
            bundleId: "com.example.authentication",
            sources: ["Sources/**"],
            metadata: .metadata(tags: ["feature:auth", "team:identity"])
        ),
        .target(
            name: "Payment",
            destinations: .iOS,
            product: .framework,
            bundleId: "com.example.payment",
            sources: ["Sources/**"],
            metadata: .metadata(tags: ["feature:payment", "team:commerce"])
        ),
        .target(
            name: "App",
            destinations: .iOS,
            product: .app,
            bundleId: "com.example.app",
            sources: ["Sources/**"],
            dependencies: [
                .target(name: "Authentication"),
                .target(name: "Payment")
            ]
        )
    ]
)

专注于带标签的目标 {#focusing-on-tagged-targets}

为目标添加标签后，你可以使用 tuist generate 命令创建一个仅包含特定目标的聚焦项目：

按标签聚焦

使用 tag: 前缀生成与特定标签匹配的所有目标的项目：

# 生成包含所有与认证相关的目标的项目
tuist generate tag:feature:auth

# 生成包含 identity 团队拥有的所有目标的项目
tuist generate tag:team:identity

按名称聚焦

你也可以按名称聚焦特定目标：

# 生成包含 Authentication 目标的项目
tuist generate Authentication

聚焦的工作原理

当你聚焦目标时：

包含的目标 - 与你的查询匹配的目标将包含在生成的项目中
依赖项 - 聚焦目标的所有依赖项将自动包含
测试目标 - 聚焦目标的测试目标将包含
排除 - 所有其他目标将从工作空间中排除

这意味着你将获得一个更小、更易于管理的工作空间，只包含你需要处理功能的内容。

标签命名约定 {#tag-naming-conventions}

虽然你可以使用任何字符串作为标签，但遵循一致的命名约定有助于保持标签的有序性：

// 按功能组织
metadata: .metadata(tags: ["feature:authentication", "feature:payment"])

// 按团队所有权组织
metadata: .metadata(tags: ["team:identity", "team:commerce"])

// 按架构层组织
metadata: .metadata(tags: ["layer:ui", "layer:business", "layer:data"])

// 按平台组织
metadata: .metadata(tags: ["platform:ios", "platform:macos"])

// 组合多个维度
metadata: .metadata(tags: ["feature:auth", "team:identity", "layer:ui"])

使用 feature:、team: 或 layer: 等前缀可以更容易地理解每个标签的用途并避免命名冲突。

系统标签 {#system-tags}

Tuist 使用 tuist: 前缀表示系统管理的标签。这些标签由 Tuist 自动应用，可用于缓存配置文件中以定位特定类型的生成内容。

可用的系统标签

标签	描述
`tuist:synthesized`	应用于 Tuist 为静态库和静态框架中的资源处理创建的综合 bundle 目标。这些 bundle 存在是为了提供资源访问器 API 的历史原因。

在缓存配置文件中使用系统标签

你可以在缓存配置文件中使用系统标签来包含或排除综合目标：

import ProjectDescription

let tuist = Tuist(
    project: .tuist(
        cacheOptions: .options(
            profiles: .profiles(
                [
                    "development": .profile(
                        .onlyExternal,
                        and: ["tag:tuist:synthesized"]  // 也缓存综合 bundle
                    )
                ],
                default: .onlyExternal
            )
        )
    )
)

::: tip 综合 BUNDLE 继承父标签

综合 bundle 目标除了接收 tuist:synthesized 标签外，还会继承其父目标的所有标签。这意味着如果你给静态库添加了 feature:auth 标签，其综合资源 bundle 将同时具有 feature:auth 和 tuist:synthesized 标签。

:::

在项目描述辅助工具中使用标签 {#using-tags-with-helpers}

你可以利用项目描述辅助工具来标准化标签在整个项目中的 적용方式：

import ProjectDescription

extension Target {
    public static func feature(
        name: String,
        team: String,
        dependencies: [TargetDependency] = []
    ) -> Target {
        .target(
            name: name,
            destinations: .iOS,
            product: .framework,
            bundleId: "com.example.\(name.lowercased())",
            sources: ["Sources/**"],
            dependencies: dependencies,
            metadata: .metadata(tags: [
                "feature:\(name.lowercased())",
                "team:\(team.lowercased())"
            ])
        )
    }
}

然后在你的清单中使用它：

import ProjectDescription
import ProjectDescriptionHelpers

let project = Project(
    name: "Features",
    targets: [
        .feature(name: "Authentication", team: "Identity"),
        .feature(name: "Payment", team: "Commerce"),
    ]
)

使用元数据标签的好处 {#benefits}

改进的开发体验

通过专注于项目的特定部分，你可以：

减小 Xcode 项目大小 - 使用更小、更快打开和导航的项目
加速构建 - 只构建当前工作所需的内容
提高专注力 - 避免来自不相关代码的干扰
优化索引 - Xcode 索引更少的代码，使自动补全更快

更好的项目组织

标签为组织代码库提供了灵活的方式：

多维度 - 按功能、团队、层、平台或任何其他维度标记目标
无需结构更改 - 添加组织结构而无需更改目录布局
横切关注点 - 单个目标可以属于多个逻辑组

与缓存集成

元数据标签与 Tuist 的缓存功能无缝协作：

# 缓存所有目标
tuist cache

# 聚焦具有特定标签的目标并使用缓存的依赖
tuist generate tag:feature:payment

最佳实践 {#best-practices}

从简单开始 - 从单一标签维度（例如功能）开始，根据需要扩展
保持一致 - 在所有清单中使用相同的命名约定
记录你的标签 - 在项目文档中保留可用标签及其含义的列表
使用辅助工具 - 利用项目描述辅助工具来标准化标签应用
定期审查 - 随着项目的发展，审查和更新你的标签策略

代码共享 - 使用项目描述辅助工具来标准化标签使用
缓存 - 将标签与缓存结合使用以获得最佳构建性能
选择性测试 - 仅针对已更改的目标运行测试