十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Fabric 项目 Go 标准目录结构重构指南:cmd/internal 分层、包重组与迁移实践

Fabric 项目 Go 标准目录结构重构指南:cmd/internal 分层、包重组与迁移实践 Fabric 项目 Go 标准目录结构重构指南cmd/internal 分层、包重组与迁移实践【免费下载链接】FabricFabric is an open-source framework for augmenting humans using AI. It provides a modular system for solving specific problems using a crowdsourced set of AI prompts that can be used anywhere.项目地址: https://gitcode.com/GitHub_Trending/fa/FabricFabric 是一个用于借助 AI 增强人类能力的开源框架提供模块化的 AI 提示词Patterns系统与多模型支持。本文基于仓库内 docs/Project-Restructured.md 重构计划文档结合当前仓库实际落地后的目录结构与源码系统讲解本次重构的动机、目标目录布局、关键改动、十步迁移流程、构建验证方法以及对外部打包与安装方式Homebrew、go install的影响。读完本文你将掌握一套可复用的 Go 应用仓库标准化重构方法并能在当前仓库中按新结构定位入口、包与数据资产。一、为什么要重构根目录混乱与非惯用 Go 结构重构计划文档明确指出旧版仓库存在三类核心问题对应 docs/Project-Restructured.md 的 Rationale 小节顶层杂乱Top-Level Clutter大量文件与目录堆在根目录开发者难以快速识别项目结构与程序入口。非惯用 Go 结构Non-Idiomatic Go StructureGo 源码分散在多个顶层目录。标准 Go 社区实践要求可执行程序入口放在cmd/私有且不可复用的包代码放在internal/。关注点混杂Mixed ConcernsGo 应用代码、Svelte Web 前端、Python 数据处理脚本、Nix 与 Docker 基础设施配置相互交织破坏了职责分离separation of concerns。重构的核心目标有三点按功能组织项目、对齐 Go 社区最佳实践、降低根目录噪音、提升开发者对项目结构的可理解性。该计划基于 GitHub issue #1127 中的讨论由ksylvan提出jaredmontoya、eugeis等人补充修订版Revision 2额外纳入了code_helper与to_pdf两个二进制工具对cmd/目录的适配。二、目标目录结构总览重构计划给出了最终目录布局见文档 Proposed Final Directory Structure 一节。以当前仓库实际落地的目录为准核心结构如下. ├── cmd # 所有可执行入口 │ ├── fabric/ # 主应用入口main.go、version.go │ ├── code2context/ # 代码扫描辅助工具 │ └── to_pdf/ # LaTeX 转 PDF 工具 ├── internal # 私有、不可复用的 Go 包 │ ├── cli/ # 全部 CLI 相关代码 │ ├── core/ # 核心应用逻辑如 PluginRegistry │ ├── domain/ # 领域类型原 common 拆分而来 │ ├── i18n/ # 国际化与语言包 │ ├── log/ # 调试日志 │ ├── plugins/ # 插件逻辑ai、db、strategy、template │ ├── server/ # 原 restapi更名以描述职责 │ ├── tools/ # 非二进制工具converter、youtube 等 │ └── util/ # 共享工具函数 ├── data │ ├── patterns/ # 全部 pattern Markdown 文件 │ └── strategies/ # 全部 strategy JSON 文件 ├── scripts # 辅助脚本与部署文件 │ ├── docker/ # Dockerfile 与部署文档 │ ├── installer/ # 安装脚本install.sh / install.ps1 │ ├── python_ui/ # Streamlit UI 与 Python 依赖 │ └── pattern_descriptions/ # pattern 描述生成工具 ├── docs/ # 文档、图片与说明 ├── web/ # Svelte 前端保持不变 ├── completions/ # Shell 补全保持不变 ├── nix/ # Nix 环境保持不变 ├── go.mod / go.sum ├── LICENSE ├── README.md ├── flake.nix / flake.lock # 必须留在根目录Nix 要求 └── .envrc # 必须留在根目录direnv 要求目录职责说明顶层目录职责包含内容当前仓库实际cmd/可执行程序入口cmd/fabric、cmd/code2context、cmd/to_pdf另有cmd/generate_changeloginternal/私有 Go 包仅限本仓库导入cli、core、domain、i18n、log、plugins、server、tools、utildata/运行时数据资产patterns/、strategies/scripts/构建与部署辅助脚本docker/、installer/、python_ui/等docs/文档与静态资源各类 Markdown、images/、swagger.yaml等需要特别说明的是计划中cmd/code_helper在当前仓库中已演化为 cmd/code2context代码上下文扫描工具这是重构落地后的实际形态文档与代码命名存在轻微差异不影响整体结构结论。三、关键改动详解1. 引入cmd/目录入口与库代码分离所有可执行入口集中到cmd/下这是 Go 社区的标准约定能让新开发者一眼看清所有应用入口也便于未来继续新增二进制工具。主入口 cmd/fabric/main.go 的当前实现非常精简印证了入口只做转发的约定package main import ( fmt os github.com/jessevdk/go-flags github.com/danielmiessler/fabric/internal/cli ) func main() { err : cli.Cli(version) if err ! nil !flags.WroteHelp(err) { fmt.Fprintf(os.Stderr, %s\n, err) os.Exit(1) } }版本号独立放在 cmd/fabric/version.go当前为v1.4.478由main.go引用。全部业务逻辑下沉到internal/cli的Cli()函数见 internal/cli/cli.go它负责解析 flagsInit()、初始化国际化i18n.Init、初始化数据库与插件注册表initializeFabric()、依次处理 setup/server/configuration/listing/management/extension 命令、YouTube 转录、HTML 可读性清理、工具处理与最终聊天请求。2. 引入internal/目录强制包私有性Go 工具链强制规定internal/目录下的包只能被同一仓库内的代码导入。这带来的实际好处是应用核心逻辑对外不可见防止其他项目误依赖明确表达这是一个应用application不是公开库library的定位未来演进如重构 API不会破坏外部使用者的构建。当前仓库的 internal/ 目录包含 9 个子包chat、cli、core、domain、i18n、log、plugins、server、tools、util。例如 internal/server 承担原 restapi 职责HTTP 服务internal/plugins 承载 ai/db/strategy/template 四类插件。3. 包重组与更名restapi→internal/server按职责命名而非实现细节命名——它提供的是 HTTP 服务而不只是 REST 接口。当前仓库中 internal/server/serve.go、internal/server/auth.go、internal/server/patterns.go 等文件正是该约定的落地。拆分common包核心数据结构迁入internal/domain工具函数就近迁移到使用它们的包中真正被多处共享的工具函数放入internal/util。当前仓库 internal/domain 下包含domain.go、attachment.go、file_manager.go、stream.go、think.go、thinking.go等文件internal/util 下则有groups_items.go与utils.go。plugins/tools拆分为internal/toolscmd/非二进制工具converter、jina、youtube、notifications、spotify、lang、githelper、custom_patterns进入internal/tools二进制工具进入cmd/。4. 数据、脚本与文档的归拢data/patterns/与strategies/是应用消费的数据资产与源码区分开。当前仓库 data/patterns 下有数百个 pattern 目录每个含system.md、user.mddata/strategies 下是aot.json、cot.json、tot.json等推理策略配置。scripts/Docker 部署文件scripts/docker/Dockerfile、安装脚本scripts/installer/install.sh、Streamlit UIscripts/python_ui与 pattern 描述生成工具scripts/pattern_descriptions统一归拢。docs/NOTES.md、图片、各类指南如 docs/rest-api.md、docs/Shell-Completions.md全部集中在 docs 下。四、十步迁移计划Step-by-Step重构计划文档给出了完整的迁移步骤当前仓库均已落地完成可作为任何 Go 仓库重构的标准操作清单创建新目录cmd/fabric、cmd/code_helper、cmd/to_pdf、internal、data、scripts、docs。移动二进制工具plugins/tools/code_helper/→cmd/code_helper/plugins/tools/to_pdf/to_pdf.go→cmd/to_pdf/main.go同时改名其余非二进制工具 →internal/tools/。移动 Go 包cli、core、plugins、restapi等目录整体迁入internal/。重命名与拆分包restapi改名server拆解common到internal/domain与internal/util。移动主入口根目录main.go→cmd/fabric/main.go。更新 Go 导入路径关键步骤使用 IDE 或goimports批量更新全部.go文件的导入路径.../fabric/cli→.../fabric/internal/cli.../fabric/plugins/tools/...→.../fabric/internal/tools/...三个二进制工具fabric、code_helper、to_pdf的导入同步更新。当前 go.mod 中模块名为github.com/danielmiessler/fabriccmd/fabric/main.go 的导入语句github.com/danielmiessler/fabric/internal/cli正是迁移后的结果。移动数据资产patterns/、strategies/迁入data/并更新应用代码中的读取路径。移动脚本与文档Docker 文件 →scripts/docker/Streamlit UI →scripts/python_ui/pattern 生成脚本 →scripts/pattern_generation/当前仓库对应 scripts/pattern_descriptions批处理文件 →scripts/NOTES.md与 images →docs/。更新构建与 CI/CD审查并更新引用旧路径的构建脚本、Makefile、CI 工作流更新 Dockerfile 路径更新 GitHub Actions 使其构建全部三个二进制./cmd/fabric、./cmd/code_helper、./cmd/to_pdf更新 README 安装说明特别更新 Update Version File and Create Tag 工作流以适配新结构。测试与验证见下一节。五、构建与验证本地构建与测试重构完成后按以下命令逐一验证对应文档 Test and Validate 小节# 主应用编译 go build ./cmd/fabric # 代码辅助工具编译 go build ./cmd/code2context # PDF 转换工具编译 go build ./cmd/to_pdf # 全量测试套件 go test ./...当前仓库 scripts/docker/Dockerfile 第 37 行的构建命令正是新结构的直接体现RUN CGO_ENABLED0 GOOSlinux go build -ldflags-s -w -o /fabric ./cmd/fabric这说明 Docker 镜像构建已从根目录main.go切换到./cmd/fabric同时开启了静态编译CGO_ENABLED0与二进制瘦身-ldflags-s -w。验证清单三个二进制均能编译通过go test ./...全量通过含 internal/cli/cli_test.go、internal/core/plugin_registry_test.go 等测试文件手动运行 CLI、API、pattern 加载与辅助工具确认功能完整。⚠️ 外部打包与分发验证剩余任务计划文档明确标注了两项需要独立验证的剩余任务Homebrew formula 更新原 formula 从根目录main.go构建该文件已不存在必须改为从./cmd/fabric构建# 原写法 def install system go, build, *std_go_args(ldflags: -s -w) end # 新写法 def install system go, build, *std_go_args(ldflags: -s -w), ./cmd/fabric end二进制名称与测试命令保持不变三个工具均可打包但主fabric二进制是首要目标。go install命令验证需要等发布打 tag 后才能验证# 主工具 go install github.com/danielmiessler/fabric/cmd/fabriclatest # 附加工具按需 go install github.com/danielmiessler/fabric/cmd/code_helperlatest go install github.com/danielmiessler/fabric/cmd/to_pdflatest六、从源码看重构后的调用链重构不仅改变了目录也让代码依赖关系更清晰。以 internal/cli/initialization.go 为例可看到新结构下初始化流程的典型调用链func initializeFabric() (registry *core.PluginRegistry, err error) { var homedir string if homedir, err os.UserHomeDir(); err ! nil { return } fabricDb : fsdb.NewDb(filepath.Join(homedir, .config/fabric)) if err fabricDb.Configure(); err ! nil { return } if registry, err core.NewPluginRegistry(fabricDb); err ! nil { return } return }这条链路展示了新结构的层次关系cmd/fabric入口→internal/cli命令编排→internal/core插件注册表→internal/plugins/db/fsdb文件系统数据库。每一层都通过internal/相对明确的导入路径协作这正是重构想要达成的可读性。七、结语重构达成与遗留事项根据 docs/Project-Restructured.md 的 RESTRUCTURING COMPLETE 一节当前重构状态如下已完成全部 10 步迁移完成全部 4 项关键结构改动落地fabric、code_helper现code2context、to_pdf三个二进制均编译通过全量测试套件通过达成标准 Go 项目布局internal/common成功拆解为internal/domain与internal/util全部导入路径更新完毕GitHub Actions 工作流已适配新结构。遗留⚠️外部打包验证Homebrew 等需单独测试go install命令验证需等发布与打 tag。这次重构的意义在于Fabric 从一个顶层大杂烩演进为标准 Go 布局的应用仓库既提升了开发者上手速度也通过internal/明确了应用边界。对于任何正在从单体脚本仓库向正式 Go 应用演进的项目本文的动机分析、目录设计、十步迁移清单与验证命令均可直接复用。【免费下载链接】FabricFabric is an open-source framework for augmenting humans using AI. It provides a modular system for solving specific problems using a crowdsourced set of AI prompts that can be used anywhere.项目地址: https://gitcode.com/GitHub_Trending/fa/Fabric创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表