README
¶
internal/ggmodule 开发注意事项
internal/ggmodule 是 gg module 命令的框架侧实现，不属于任何一个具体业务 module。
修改这个包时，必须保持它和真实内置 module 解耦。
边界规则
internal/ggmodule的代码和测试不应依赖真实的module/authz、module/mfa、module/logmgmt、module/helloworld、module/version等业务 module。- 测试不应引用真实的
internal/model/<module>或internal/service/<module>业务实现。 - 需要 module、model、service、middleware fixture 时，在测试临时目录中创建 fake framework。
- fake framework 根目录应模拟
internal/gst/go.mod，module path 使用github.com/hydroan/gst。 - fixture 名称使用中性命名，例如
copytest、aliased、configured、modelcopytest、servicecopytest。 - 不要用真实业务名作为“方便的样例”，否则后续业务重构会误伤
ggmodule测试。
测试组织
add、remove、catalog相关测试只验证 module 命令语义，应使用 fakemodule/<name>/register.go。- 可添加 module 使用无参
Register()。 - 不可添加 module 使用带参数
Register(...)。 - 包名和目录名不一致时，使用 fake package alias 测试导入别名逻辑。
copy相关测试应在临时 fake framework 中同时创建：module/<name>/module.jsoninternal/model/<name>internal/service/<name>- 必要时创建
middleware
- 不要通过 symlink 或路径指向仓库中的真实 module 作为 copy source。
- 辅助函数应放在对应测试文件或
test_helpers_test.go，并保持 fixture 语义中性。
Documentation
¶
Overview ¶
Package ggmodule implements the behavior behind the gg module command family.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChangeResult ¶
type ChangeResult struct {
Module Module
Status ChangeStatus
Path string
}
ChangeResult is returned by add/remove commands so the Cobra layer can decide how to present the operation without knowing AST details.
func AddModule ¶
func AddModule(projectDir string, name string) (ChangeResult, error)
AddModule registers a built-in framework module in the current project's module/module.go.
This is the framework-module registration mode. It does not copy model or service source into the project. Keeping it separate from Copy keeps the two ownership models explicit:
- add/remove manages a framework import plus pkg.Register() call.
- copy creates local source files that the project owns afterwards.
func RemoveModule ¶
func RemoveModule(projectDir string, name string) (ChangeResult, error)
RemoveModule unregisters a built-in framework module from module/module.go.
Removal only deletes the import and the zero-argument Register call managed by gg module add. It intentionally does not delete model/service source files; local source cleanup belongs to the source-copy flow and is a separate user decision.
type ChangeStatus ¶
type ChangeStatus string
ChangeStatus describes whether a module command changed module/module.go.
const ( ChangeCreated ChangeStatus = "created" ChangeRemoved ChangeStatus = "removed" ChangeSkipped ChangeStatus = "skipped" )
type CopyExecution ¶
type CopyExecution struct {
Plan *CopyPlan
Options CopyOptions
RunGen func() error
WrittenFiles []string
}
CopyExecution applies a previously checked CopyPlan.
func (*CopyExecution) Run ¶
func (e *CopyExecution) Run() error
Run applies the copy in the required order: model source first, gg gen second, service/helper business logic last. It does not roll back partial writes; the command prints the prune cleanup path when a failure happens after files were written.
type CopyOptions ¶
CopyOptions configures the local-source copy workflow.
type CopyPlan ¶
type CopyPlan struct {
Name string
ProjectModulePath string
FrameworkRoot string
ModelDir string
ServiceDir string
SourceModelDir string
SourceServiceDir string
TargetModelDir string
TargetServiceDir string
TargetMiddlewareDir string
TargetModelImportPath string
Actions []moduleCopyAction
Middleware []moduleCopyMiddleware
Files []moduleCopyFile
// ExtraModelFiles is warning-only upgrade guidance for files already
// present in TargetModelDir that do not have a matching source file under
// SourceModelDir in this copy plan. Module copy reports these files so
// callers can clean up stale local copies after framework module changes,
// but it must not delete them automatically because model directories can
// intentionally contain project-owned files.
ExtraModelFiles []string
// ExtraServiceFiles is warning-only upgrade guidance for target service
// files that are already present but are not produced by this copy plan.
// Module copy must not delete them automatically because service packages can
// intentionally contain project-owned adapters next to copied module code.
ExtraServiceFiles []string
ExcludeSourceFiles []string
PostNotes []string
}
CopyPlan describes the final files and source mappings for one module copy.
func BuildCopyPlan ¶
func BuildCopyPlan(name string, opts CopyOptions) (*CopyPlan, error)
BuildCopyPlan is the copy-ready preflight. It resolves framework source paths, parses source DSL through the same codegen model parser used by gg gen, computes final rewritten file contents, and checks target conflicts.
func (*CopyPlan) ExtraModelTargets ¶
ExtraModelTargets returns current-project model files that are not part of the current copy plan. These are warnings only: copied model packages can contain project-owned files, and module copy cannot prove an extra file is obsolete just because the framework source no longer produces it.
func (*CopyPlan) ExtraServiceTargets ¶
ExtraServiceTargets returns current-project service files that are not part of the current copy plan. These are warnings only: copied service packages can contain project-owned adapters, and module copy cannot prove an extra file is obsolete just because the framework source no longer produces it.
func (*CopyPlan) HelperTargets ¶
HelperTargets returns current-project helper service files that copy will write.
func (*CopyPlan) MiddlewareTargets ¶
MiddlewareTargets returns manifest-declared middleware files copied into the current project's middleware package.
func (*CopyPlan) ModelTargets ¶
ModelTargets returns current-project model files that copy will write.
func (*CopyPlan) ServiceTargets ¶
ServiceTargets returns current-project action service files that copy will merge.
type Module ¶
Module describes one built-in framework module that gg can manage.
Name is the directory under the framework's module/ tree. PackageName is the actual Go package declared by register.go; those can differ, for example module/aliased uses package aliasedmod. ImportPath is the framework import path a project module/module.go should import when it wants to use the module. Addable is deliberately separate from discovery: gg module list should show every discoverable framework module, while gg module add can only automate modules whose Register function can be called without project-specific args. Copyable is true only when module/<name>/module.json exists, which is the explicit copy contract required by gg module copy.
func ListModules ¶
ListModules returns built-in framework modules discovered from module/*/register.go.
The catalog is intentionally derived from source instead of maintained as a static list. New framework modules become visible to gg as soon as they expose a register.go file, and tests cannot drift from the actual module tree.
Source Files