模式：结构体使用 名词动作 + UseCase。DTO 使用 名词动作 + Input / Output。

结构

package usecase

import (
	"context"

	"github.com/cristiano-pacheco/bricks/pkg/logger"
	"github.com/cristiano-pacheco/bricks/pkg/validator"
	"github.com/cristiano-pacheco/gomies/internal/modules/<module>/model"
	"github.com/cristiano-pacheco/gomies/internal/modules/<module>/ports"
)

type NounActionInput struct {
	FirstName string `validate:"required,min=3,max=255"`
	LastName  string `validate:"required,min=3,max=255"`
	Password  string `validate:"required,min=8"`
	Email     string `validate:"required,email,max=255"`
}

type NounActionOutput struct {
	FirstName string
	LastName  string
	Email     string
	UserID    uint64
}

type NounActionUseCase struct {
	userRepository ports.UserRepository
	validator      validator.Validator
	logger         logger.Logger
}

func NewNounActionUseCase(
	userRepository ports.UserRepository,
	validator validator.Validator,
	logger logger.Logger,
) *NounActionUseCase {
	return &NounActionUseCase{
		validator: validator,
		logger:    logger,
	}
}

func (uc *NounActionUseCase) Execute(ctx context.Context, input NounActionInput) (NounActionOutput, error) {
	err := uc.validator.Struct(input)
	if err != nil {
		uc.logger.Error("user creation validation failed", logger.Error(err))
		return NounActionOutput{}, err
	}

	userModel := model.UserModel{
		FirstName: input.FirstName,
		LastName:  input.LastName,
		Email:     input.Email,
		Password:  input.Password,
	}

	createdUser, err := uc.userRepository.Create(ctx, userModel)
	if err != nil {
		uc.logger.Error("user creation failed", logger.Error(err))
		return NounActionOutput{}, err
	}

	output := NounActionOutput{
		UserID:    createdUser.ID,
		FirstName: createdUser.FirstName,
		LastName:  createdUser.LastName,
		Email:     createdUser.Email,
	}

	return output, nil
}

Execute 方法流程

1. 验证输入 — 始终是第一步：uc.validator.Struct(input)
2. 业务逻辑 — 仓库调用、服务调用、领域检查
3. 记录每个错误 在返回之前
4. 返回类型化错误 来自 errs 包
5. 映射结果 到 Output 结构体并返回

输入验证

通过 Input 结构体上的 validate 结构体标签定义约束。在 Execute 内部的第一行调用 uc.validator.Struct(input)。直接返回验证错误 — 共享的验证器会格式化它们。

常用标签：required、min=N、max=N、email、oneof=val1 val2 val3

错误处理

来自仓库、服务或外部调用的每个错误在返回前必须被记录：

entity, err := uc.entityRepo.FindByID(ctx, input.ID)
if err != nil {
	uc.logger.Error("error finding entity by id", logger.Error(err))
	return EntityGetOutput{}, err
}

对于预期不存在（非致命错误）的未找到检查：

entity, err := uc.entityRepo.FindByEmail(ctx, input.Email)
if err != nil && !errors.Is(err, bricserrs.ErrRecordNotFound) {
	uc.logger.Error("error finding entity by email", logger.Error(err))
	return EntityCreateOutput{}, err
}
if entity.ID != 0 {
	return EntityCreateOutput{}, errs.ErrEmailAlreadyInUse
}

导入 bricks 错误：bricserrs "github.com/cristiano-pacheco/bricks/errs"

返回来自 errs 的类型化模块错误 — 永远不要使用 errors.New(...)。

依赖项

每个用例都包含这些共享依赖项：

• validator.Validator — 通过标签进行输入结构体验证
• logger.Logger — 错误日志记录

永远不要为模块依赖项注入具体类型。

Fx 装配

在模块的 fx.go 中，注册原始构造函数和一个包装所有用例的 provideDecoratedUseCases 函数。

单个用例

var Module = fx.Module(
	"<module-name>",
	fx.Provide(
		usecase.NewEntityCreateUseCase,
		provideDecoratedUseCases,
	),
)

type decorateUseCasesIn struct {
	fx.In
	UseCaseDecoratorFactory *ucdecorator.Factory
	EntityCreateUseCase     *usecase.EntityCreateUseCase
}

type decorateUseCasesOut struct {
	fx.Out
	EntityCreateUseCase ucdecorator.UseCase[usecase.EntityCreateInput, usecase.EntityCreateOutput]
}

func provideDecoratedUseCases(in decorateUseCasesIn) decorateUseCasesOut {
	return decorateUseCasesOut{
		EntityCreateUseCase: ucdecorator.Wrap(in.UseCaseDecoratorFactory, in.EntityCreateUseCase),
	}
}

反模式

缺少输入验证 — 错误示例

func (uc *UserCreateUseCase) Execute(ctx context.Context, input UserCreateInput) (UserCreateOutput, error) {
	// 错误：跳过了 uc.validator.Struct(input)
	user, err := uc.userRepository.Create(ctx, ...)

未记录的错误 — 错误示例

// 错误
entity, err := uc.entityRepo.FindByID(ctx, input.ID)
if err != nil {
	return EntityGetOutput{}, err
}

// 正确
entity, err := uc.entityRepo.FindByID(ctx, input.ID)
if err != nil {
	uc.logger.Error("error finding entity by id", logger.Error(err))
	return EntityGetOutput{}, err
}

原始错误 — 错误示例

// 错误
return UserCreateOutput{}, errors.New("email already in use")

// 正确
return UserCreateOutput{}, errs.ErrEmailAlreadyInUse

在用例内部进行追踪/指标记录 — 错误示例

// 错误：可观测性应属于 ucdecorator
ctx, span := trace.Span(ctx, "UserCreateUseCase.Execute")
defer span.End()

具体类型注入 — 错误示例

// 错误
type UserCreateUseCase struct {
	userRepository *repository.UserRepository
}

// 正确
type UserCreateUseCase struct {
	userRepository ports.UserRepository
}

错误命名 — 错误示例

// 错误：Input/Output 未遵循名词动作模式
type CreateUserInput struct {}
type CreateUserOutput struct {}

// 正确
type UserCreateInput struct {}
type UserCreateOutput struct {}

冗余注释 — 错误示例

// 错误
// Execute executes the user create use case.
func (uc *UserCreateUseCase) Execute(...) {}

// NewUserCreateUseCase creates a new UserCreateUseCase.
func NewUserCreateUseCase(...) *UserCreateUseCase {}

每个错误都必须被记录。每个用例必须在其自己的用例文件中定义自己的 Input 和 Output 类型，并且这些边界类型必须是自包含的。Input/Output 绝对不能嵌入或引用共享模块的 DTO/模型。Input/Output 必须显式声明所有字段，可以直接声明，也可以通过在同一用例文件中声明的嵌套结构体声明。Input/Output 类型是该用例契约私有的，绝不能由其他用例重用。共享的形状应属于仓库/服务/领域层，而不是用例边界契约。Input/Output 类型不能有 json 标签。

关键规则

1. 命名：结构体 NounActionUseCase，输入 NounActionInput，输出 NounActionOutput。没有例外。
2. 输入和输出：始终定义两个结构体，即使为空。
3. 先验证：uc.validator.Struct(input) 始终是 Execute 中的第一个调用。
4. 记录每个错误：在每个错误返回之前使用 uc.logger.Error(msg, logger.Error(err))。
5. 类型化错误：返回来自模块 errs 包的错误 — 永远不要使用 errors.New(...)。
6. 无追踪/指标：可观测性由外部的 ucdecorator 处理。
7. 端口接口：模块依赖必须是 ports.* 接口。
8. 单一 Execute：一个公共方法 Execute(ctx context.Context, input Input) (Output, error)。
9. 构造函数返回指针：NewNounActionUseCase(...) 返回 *NounActionUseCase。
10. 无独立函数：逻辑仅在 Execute 或私有方法中。
11. 无冗余注释：不要重复方法/构造函数名称。
12. Fx 装饰：通过 fx.In/fx.Out 结构体使用 ucdecorator.Wrap 包装。

反模式：独立函数

当文件中存在带有方法的结构体时，禁止在包级别使用独立函数。它们会污染包命名空间，可能与其他服务文件中的助手函数冲突，并分散属于该结构体的逻辑。

工作流程

1. 创建 usecase/<名词>_<动作>_usecase.go
2. 定义 Input（带 validate 标签）、Output、结构体、构造函数、Execute
3. 将 Fx 装配添加到模块的 fx.go（构造函数 + provideDecoratedUseCases）
4. 运行 make lint 和 make nilaway 以验证用例遵循所有模式且没有空指针风险。

每周安装数

1

仓库

cristiano-pache…ai-rules

首次出现

今天

安全审计

Gen Agent Trust Hub通过Socket失败Snyk通过

安装于

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

Pattern: NounAction + UseCase for the struct. NounAction + Input / Output for DTOs.

Structure

package usecase

import (
	"context"

	"github.com/cristiano-pacheco/bricks/pkg/logger"
	"github.com/cristiano-pacheco/bricks/pkg/validator"
	"github.com/cristiano-pacheco/gomies/internal/modules/<module>/model"
	"github.com/cristiano-pacheco/gomies/internal/modules/<module>/ports"
)

type NounActionInput struct {
	FirstName string `validate:"required,min=3,max=255"`
	LastName  string `validate:"required,min=3,max=255"`
	Password  string `validate:"required,min=8"`
	Email     string `validate:"required,email,max=255"`
}

type NounActionOutput struct {
	FirstName string
	LastName  string
	Email     string
	UserID    uint64
}

type NounActionUseCase struct {
	userRepository ports.UserRepository
	validator      validator.Validator
	logger         logger.Logger
}

func NewNounActionUseCase(
	userRepository ports.UserRepository,
	validator validator.Validator,
	logger logger.Logger,
) *NounActionUseCase {
	return &NounActionUseCase{
		validator: validator,
		logger:    logger,
	}
}

func (uc *NounActionUseCase) Execute(ctx context.Context, input NounActionInput) (NounActionOutput, error) {
	err := uc.validator.Struct(input)
	if err != nil {
		uc.logger.Error("user creation validation failed", logger.Error(err))
		return NounActionOutput{}, err
	}

	userModel := model.UserModel{
		FirstName: input.FirstName,
		LastName:  input.LastName,
		Email:     input.Email,
		Password:  input.Password,
	}

	createdUser, err := uc.userRepository.Create(ctx, userModel)
	if err != nil {
		uc.logger.Error("user creation failed", logger.Error(err))
		return NounActionOutput{}, err
	}

	output := NounActionOutput{
		UserID:    createdUser.ID,
		FirstName: createdUser.FirstName,
		LastName:  createdUser.LastName,
		Email:     createdUser.Email,
	}

	return output, nil
}

Execute Method Flow

1. Validate input — always first: uc.validator.Struct(input)
2. Business logic — repository calls, service calls, domain checks
3. Log every error before returning it
4. Return typed errors from errs package
5. Map result to Output struct and return

Input Validation

Define constraints via validate struct tags on the Input struct. Call uc.validator.Struct(input) as the first line inside Execute. Return validation errors directly — the shared validator formats them.

Common tags: required, min=N, max=N, email, oneof=val1 val2 val3

Error Handling

Every error from a repository, service, or external call MUST be logged before returning:

entity, err := uc.entityRepo.FindByID(ctx, input.ID)
if err != nil {
	uc.logger.Error("error finding entity by id", logger.Error(err))
	return EntityGetOutput{}, err
}

For not-found checks where absence is expected (not a terminal error):

entity, err := uc.entityRepo.FindByEmail(ctx, input.Email)
if err != nil && !errors.Is(err, bricserrs.ErrRecordNotFound) {
	uc.logger.Error("error finding entity by email", logger.Error(err))
	return EntityCreateOutput{}, err
}
if entity.ID != 0 {
	return EntityCreateOutput{}, errs.ErrEmailAlreadyInUse
}

Import for bricks errors: bricserrs "github.com/cristiano-pacheco/bricks/errs"

Return typed module errors from errs — never errors.New(...).

Dependencies

Every use case includes these shared dependencies:

• validator.Validator — input struct validation via tags
• logger.Logger — error logging

Never inject concrete types for module dependencies.

Fx Wiring

In the module's fx.go, register raw constructors and a single provideDecoratedUseCases function that wraps them all.

Single use case

var Module = fx.Module(
	"<module-name>",
	fx.Provide(
		usecase.NewEntityCreateUseCase,
		provideDecoratedUseCases,
	),
)

type decorateUseCasesIn struct {
	fx.In
	UseCaseDecoratorFactory *ucdecorator.Factory
	EntityCreateUseCase     *usecase.EntityCreateUseCase
}

type decorateUseCasesOut struct {
	fx.Out
	EntityCreateUseCase ucdecorator.UseCase[usecase.EntityCreateInput, usecase.EntityCreateOutput]
}

func provideDecoratedUseCases(in decorateUseCasesIn) decorateUseCasesOut {
	return decorateUseCasesOut{
		EntityCreateUseCase: ucdecorator.Wrap(in.UseCaseDecoratorFactory, in.EntityCreateUseCase),
	}
}

Anti-Patterns

Missing input validation — BAD

func (uc *UserCreateUseCase) Execute(ctx context.Context, input UserCreateInput) (UserCreateOutput, error) {
	// BAD: skipped uc.validator.Struct(input)
	user, err := uc.userRepository.Create(ctx, ...)

Unlogged error — BAD

// BAD
entity, err := uc.entityRepo.FindByID(ctx, input.ID)
if err != nil {
	return EntityGetOutput{}, err
}

// GOOD
entity, err := uc.entityRepo.FindByID(ctx, input.ID)
if err != nil {
	uc.logger.Error("error finding entity by id", logger.Error(err))
	return EntityGetOutput{}, err
}

Raw errors — BAD

// BAD
return UserCreateOutput{}, errors.New("email already in use")

// GOOD
return UserCreateOutput{}, errs.ErrEmailAlreadyInUse

Tracing/metrics inside use case — BAD

// BAD: observability belongs in ucdecorator
ctx, span := trace.Span(ctx, "UserCreateUseCase.Execute")
defer span.End()

Concrete type injection — BAD

// BAD
type UserCreateUseCase struct {
	userRepository *repository.UserRepository
}

// GOOD
type UserCreateUseCase struct {
	userRepository ports.UserRepository
}

Wrong naming — BAD

// BAD: Input/Output not following NounAction pattern
type CreateUserInput struct {}
type CreateUserOutput struct {}

// GOOD
type UserCreateInput struct {}
type UserCreateOutput struct {}

Redundant comments — BAD

// BAD
// Execute executes the user create use case.
func (uc *UserCreateUseCase) Execute(...) {}

// NewUserCreateUseCase creates a new UserCreateUseCase.
func NewUserCreateUseCase(...) *UserCreateUseCase {}

Every error must be logged. Each use case must define its own Input and Output types in its own use case file, and those boundary types must be self-contained. Input/Output MUST NOT embed or reference shared module DTOs/models Input/Output MUST declare all fields explicitly, either directly or via nested structs declared in the same use case file. Input/Output types are private to that use case contract and MUST NOT be reused by other use cases. Shared shapes belong in repository/service/domain layers, not in use case boundary contracts. Input/Output types must not have json tags

Critical Rules

1. Naming : Struct NounActionUseCase, Input NounActionInput, Output NounActionOutput. No exceptions.
2. Both Input and Output : Always define both structs, even if empty.
3. Validate first : uc.validator.Struct(input) is always the first call in Execute.
4. Log every error : uc.logger.Error(msg, logger.Error(err)) before every error return.
5. Typed errors : Return errors from module errs package — never errors.New(...).
6. No tracing/metrics : Observability handled by ucdecorator externally.
7. Port interfaces : Module deps must be ports.* interfaces.
8. Single Execute : One public method Execute(ctx context.Context, input Input) (Output, error).
9. Constructor returns pointer : NewNounActionUseCase(...) returns *NounActionUseCase.
10. No standalone functions : Logic in Execute or private methods only.
11. No redundant comments : Do not restate method/constructor names.
12. Fx decoration : Wrap with ucdecorator.Wrap via fx.In/fx.Out structs.

Anti-pattern: Standalone functions

Standalone functions at the package level are forbidden when a struct with methods exists in the file. They pollute the package namespace, can collide with helpers in other service files, and fragment logic that belongs to the struct.

Workflow

1. Create usecase/<noun>_<action>_usecase.go
2. Define Input (with validate tags), Output, struct, constructor, Execute
3. Add Fx wiring to module's fx.go (constructor + provideDecoratedUseCases)
4. Run make lint and make nilaway to verify the use case follows all patterns and has no nil pointer risks.

Weekly Installs

1

Repository

cristiano-pache…ai-rules

First Seen

Today

Security Audits

Gen Agent Trust HubPassSocketFailSnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1