Gitea 组件仓库设计指南

目标

  • 了解组件仓库的设计原则
  • 掌握组件仓库的创建和管理

大纲

  1. 组件仓库设计原则
  2. 组件仓库创建和管理
  3. 组件仓库使用

1. 组件仓库设计原则

  1. 组件仓库名称必须符合组织内的仓库命名要求
  2. 名称不能重复,不得使用中文字符
  3. 根据仓库创建要求，应当包含README.md、.gitignore、.clang-format文件
  4. 应当包含功能更完整的代码示例example
  5. 应当包含功能更完整的测试代码test
  6. 应当包含设计说明文档doc
  7. 应当减少组件依赖，增加组件的独立性
  8. 应当使用ci/cd流水线进行自动化构建、测试
  9. 应当对接口文件进行规范注释
  10. 应当拥有版本标识信息
  11. 接口文件放在include/inc,源码文件放在src,测试文件放在test,示例文件放在example
  12. 私有头文件不应放在include/inc根目录下,应当放在src目录下使不被外部引用

1.1 必要文件与目录说明

序号 名称 类型 说明
1 README.md 文件 组件仓库的说明文档，应当包含组件仓库的介绍、使用方法、安装步骤、配置文件说明、接口说明、版本信息等，使用 Markdown 格式编写。
2 .gitignore 文件 仓库忽略文件，应当列出需要被 Git 忽略的文件或目录，使用 gitignore 格式编写。
3 .clang-format 文件 代码风格配置文件，应当使用 clang-format 格式编写。
4 example/ 目录 代码示例目录，应当包含组件仓库的代码示例，用于演示组件的典型用法。
5 test/ 目录 测试代码目录，应当包含组件仓库的测试代码，并按约定的测试代码风格组织。
6 doc/ 目录 设计说明文档目录，应当包含组件仓库的设计说明文档。
7 include/ 或 inc/ 目录 接口头文件目录，应当包含对外暴露的接口文件，并按照接口文件规范进行组织与注释。
8 src/ 目录 源码目录，应当包含组件仓库的实现源码，并按照约定的源码组织结构编写。
9 port/ 目录 接口层模板或者示例，用户根据文件引导调用第三方组件。

2. 组件仓库创建和管理

2.1 从项目中裁剪出组件仓库

将普通项目中的可复用代码抽离为独立组件仓库，便于在组织内或公开场景下复用、版本管理和协作维护。

适用场景

  • 项目内某模块被多个项目或团队复用
  • 希望将通用能力独立发布、版本化
  • 需要对外或对组织内公开可复用组件

抽离与准备流程

  1. 识别可复用范围
    在现有项目中圈定要抽离的目录/文件，确认其职责单一、接口清晰、可独立编译或集成。

  2. 按设计原则准备仓库结构
    参照本文档「组件仓库设计原则」与「必要文件与目录说明」，在本地新建或整理出符合规范的目录（如 include/ 或 inc/、src/、example/、test/、doc/ 等），并将抽离的代码放入对应位置。

  3. 解耦与通用化
    若原组件与业务强耦合，需做适度重构：去除项目特有依赖、用配置或接口替代硬编码、减少对其它业务模块的依赖，提高组件通用性。

  4. 处理对外依赖
    若组件依赖其它组件或平台接口，应通过 port/ 等接口层抽象（如适配层、回调接口），保证可移植性，并在 README 或 doc 中说明移植与配置方法。

  5. 补齐规范文件与质量保障
    补充 README.md、.gitignore、.clang-format，编写示例（example）、测试（test）、设计说明（doc），并接入 CI/CD 实现自动化构建与测试。

  6. 创建独立仓库并推送
    在 Gitea 上创建新仓库，在本地初始化 Git、添加远程、提交并推送。若组织有命名与分支规范，需一并遵守。

  7. （可选）用 submodule 嵌入原项目
    组件仓库创建并发布后，可在原项目或其它项目中通过 Git submodule 将该组件仓库嵌入为子模块，便于固定版本、统一更新。具体操作见「组件仓库使用」或 submodule 相关文档。

2.2 规范的项目组件直接推送到组件仓库

部分项目在设计之初就按组件化进行目录规划，组件代码本身已基本符合「组件仓库设计原则」，只是长期随业务仓库一起演进，现在希望将其独立为组件仓库单独维护。

适用场景

  • 组件目录结构、命名规范、接口设计等已经相对完备，无需或只需极少重构
  • 希望完整保留该组件目录下的历史提交记录，作为组件演进的审计与追溯依据

操作流程

利用 git subtree 的特性，可以将工程仓库中指定目录的完整历史拆分为一个独立分支，并推送到新的组件仓库。典型流程如下（假设组件目录为 path/to/component）：

  1. 在现有项目中创建拆分分支
    在业务仓库根目录执行：

    # 从当前分支中，将指定目录拆分为独立分支 component-split
git subtree split --prefix=path/to/component -b component-split

  2. 在 Gitea 上创建组件仓库并添加远程

    • 在 Gitea 上新建组件仓库（名称、访问权限等按组织规范配置）
    • 在本地业务仓库中添加远程地址，例如：
    git remote add component-origin http://<gitea-server>/<group>/component.git

  3. 推送拆分分支到组件仓库

    # 将拆分出来的 component-split 分支推送到组件仓库的主分支
git push component-origin component-split:master

    推送完成后，新组件仓库将包含 path/to/component 目录下的完整提交历史。

  4. （可选）在原项目中改为以组件仓库方式使用

    • 可以保留原目录不动，仅在需要时在组件仓库中继续演进
    • 也可以在业务仓库中删除原组件目录，改为通过 submodule 或包管理方式引用新组件仓库，具体见后文「组件仓库使用」章节。

3. 组件仓库使用

组件仓库创建完成后，可以通过以下方式在项目中集成和更新组件：

  1. 以 Git submodule 形式引入组件仓库，固定组件版本，便于统一升级
  2. 以包管理或内部依赖的形式引用组件仓库（例如通过内部包仓库、构建系统依赖等）
  3. 具体命令与更多使用场景可参考本项目中的 Git 子仓库/子树使用指南（如 git_subtree_guide.md 等文档），并结合团队现有的集成规范执行。