让 Go 也能注解使用装饰器，切面(AOP)、代理(Proxy)任意函数和方法的神器！

go-decorator， 可以让 Go 通过注释注解使用装饰器的工具，通过装饰器能够切面(AOP)、代理(Proxy)任意的函数和方法，提供观察和控制函数的能力。

go-decorator 在八月份发布了初版，经过几个月的多轮迭代，代表着里程碑的版本 v0.20.0 发布了。该版本已经完成了最初开发此工具时设立的目标，即实现比如自由定义函数为装饰器、允许使用装饰器参数、方法集 type 快捷注释等等需求，这些最常用的功能现都集成在了这个版本中，同时，保持开发者在使用工具和编写代码时的简单和便捷，减少开发中的心智负担。

目前版本处于公开测试阶段，欢迎 Golang 的开发者安装体验，如有任何问题，可以留言评论或者通过 GitHub Issue 提出建议和意见。

Feature

• 添加注释 //go:decor F 即可使用装饰器（F 为装饰器函数），快速完成“样板代码注入、非侵入式改变函数行为、控制逻辑流程”等逻辑；
• 可以自由定义函数作为装饰器，应用于任意一级函数和方法上（top-level function or method）;
• 支持使用多个（行） //go:decor 装饰器装饰目标函数;
• 支持注释 type T types 类型声明，decorator 会自动装饰代理以 T 或者 *T 为接收者的所有方法；
• 装饰器支持可选参数，给开发带来更多可能；
• 支持编译时 lint 验证，保证 Go 编译代码的健壮性；
• 提供友好的错误提示，可在编译时发现问题并给出错误原因和错误行号（例如未定义的装饰器或未引用的包等）;
• 仅在编译时增强目标函数，不会降低编译后程序的性能，亦没有反射操作;

装饰器的使用场景，可以参考其他语言，比如 Python、TypeScript。（非常适合在缓存、鉴权、日志等场景使用，作为辅助手段解放重复编码的困扰）。

go-decorator 是一种编译时代码注入技术。使用它不会影响您项目的源文件，并且不会在项目中生成额外的 .go 文件和其他冗余文件。这种注入方法与 go:generate 生成方式截然不同。

Requirement

• go 1.18 及其以上
• go.mod 项目

Install

通过 go install 安装:

$ go install github.com/dengsgo/go-decorator/cmd/decorator@latest

运行 decorator，显示 decorator 版本信息即为安装成功。

$ decorator
decorator v0.20.0 beta , https://github.com/dengsgo/go-decorator

Usage

decorator 依赖原生 go 命令来调用它，使用只需在 go 的子命令中加入 -toolexec decorator 参数即可。 例如：

Code

在你的项目引入装饰器依赖（必须是 go.mod 项目）:

$ go get -u github.com/dengsgo/go-decorator

编写类似代码：

package main

import (
    "github.com/dengsgo/go-decorator/decor"
    "log"
)

func main() {
    // 正常调用你的函数。
    // 由于这是一个声明使用装饰器logging的函数, 
    // decorator 编译链会在编译代码时注入装饰器方法logging的调用。
    // 所以使用上面的方式编译后运行，你会得到如下输出：
    // 
    // 2023/08/13 20:26:30 decorator function logging in []
    // 2023/08/13 20:26:30 this is a function: myFunc
    // 2023/08/13 20:26:30 decorator function logging out []
    // 
    // 而不是只有 myFunc 本身的一句输出。
    // 也就是说通过装饰器改变了这个方法的行为！
    myFunc() 
}

// 通过使用 go:decor 注释声明该函数将使用装饰器logging来装饰。
//
//go:decor logging
func myFunc() {
    log.Println("this is a function: myFunc")
}

// 这是一个普通的函数
// 但是它实现了 func(*decor.Context [, ...any]) 类型，因此它还是一个装饰器方法，
// 可以在其他函数上使用这个装饰器。
// 在函数中，ctx 是装饰器上下文，可以通过 ctx 获取到目标函数的函数名、出入参
// 以及执行目标函数。
// 如果函数中没有执行 ctx.TargetDo(), 那么意味着目标函数不会执行，
// 即使你代码里调用了被装饰的目标函数！这时候，目标函数返回的都是零值。
// 在 ctx.TargetDo() 之前，可以修改 ctx.TargetIn 来改变入参值。
// 在 ctx.TargetDo() 之后，可以修改 ctx.TargetOut 来改变返回值。
// 只能改变出入参的值。不要试图改变他们的类型和数量，这将会引发运行时 panic !!!
func logging(ctx *decor.Context) {
    log.Println("decorator function logging in", ctx.TargetIn)
    ctx.TargetDo()
    log.Println("decorator function logging out", ctx.TargetOut)
}

带有参数的装饰器用法：

package main

import (
    "github.com/dengsgo/go-decorator/decor"
)

func main()  {
    optionalParametersFuncDemo()
}

// 它也是装饰器，不同于普通装饰器，它允许目标函数额外提供参数 `level` 。
// decorator 提供了 lint 语法给开发者，在编译代码时强制进行校验。比如:
// `required` 要求目标函数必须对该字段传值；
// `nonzero` 要求目标函数传值不能时空值。
// 如果编译时校验不通过，会编译失败。
// 使用方式如下:(更多用法查看 Guide.md)：
//
//go:decor-lint required: {level}
//go:decor-lint nonzero: {level}
func levelLogging(ctx *decor.Context, level string)  {
    if level == "debug" {
        // to do something
    }
    ctx.TargetDo()
}

// 这个方法使用了装饰器 levelLogging，并且额外传递了 `level` 参数值 "debug" 给装饰器。
// 
//go:decor levelLogging#{level: "debug"}
func optionalParametersFuncDemo()  {
    // function code
}

给 type T types 类型声明添加注释 //go:decor F，decorator 会自动使用装饰器 F 装饰代理以 T 或者 *T 为接收者的所有方法：

package main

import (
    "github.com/dengsgo/go-decorator/decor"
)

// 添加注释//go:decor dumpTargetType，
// structType 的方法集 Name、StrName、empty 会自动被装饰器 dumpTargetType 代理装饰。
// 方法的接收者可以是值接收者，也可以是指针接收者，都会被自动装饰。

//go:decor dumpTargetType
type structType struct {
    name string
}

func (s *structType) Name() string {
    return s.name
}

func (s *structType) StrName(name string) {
    s.name = name
}

func (s *structType) empty() {}

Issue

发现任何问题，都可以在这里反馈. github issues 。

欢迎 Star 关注项目发展！