deepcopy-gen

README

deepcopy生成器

背景

• 基于 reflect 的 DeepCopy 会比自己实现一个 DeepCopy 慢一个数量级
• 自己对每个对象实现一个 DeepCopy 会带来很大的开发负担，并且很难保证一致性
• 静态语言的问题还是应该由静态语言的方案来解决 --- 代码生成

安裝

go install github.com/davionlee/deepcopy-gen

需要仓库为public

来源

本库基于k8s.io/gengo/examples/deepcopy-gen抽离出来，做了以下修改:

1. 忽略bson:"-" 和 copy:"-" 已经小写开头字段的拷贝
2. 去除对GOPATH的依赖，并且支持不同的go mod目录放置(你可以放在src/gs下，也可放在src/github.com/davionlee/gs下，生成的deepcopy_generated会正确位于对应目录)
3. 生成的DeepCopy方法返回interface{}，而非具体的对象，方便上层做接口统一

使用

有两种方案来标记生成哪些类型的DeepCopy方法，一种是按类型进行结构生成，即在struct定义上方加上注释:

// +deepcopy-gen=true
type A struct {
	...
}

另一种是按照package来生成，即在package的某个文件(建议是doc.go)中加上注释行:

// +deepcopy-gen=package

此时package内的所有struct都会生成DeepCopy方法，如果有些类型不需要生成DeepCopy方法，则单独为其注释:

// +deepcopy-gen=false
type B struct {
	...
}

标记完成后，执行以下命令来生成：

deepcopy-gen -i packagepath -p rootpackage

如你在项目gs(github.com/davionlee/gs)的根目录执行该命令，要对github.com/davionlee/gs/game/play/mplayer包进行生成，则:

deepcopy-gen -i github.com/davionlee/gs/game/play/mplayer -p gs

其它

1. deepcopy-gen基于静态类型生成，因此不能拷贝 interface{} 字段，解决方案: 避免使用 interface{}，或者自己写一层 DeepCopy()，接口转换后调用到实际对象的 gen DeepCopy()
2. deepcopy-gen 不能拷贝数组字段，如 skill [3]int32，解决方案: 换成 skill []int32
3. 对于一些特殊的对象，比如战报，可变更的只有战报的过期时间(收藏操作)，而二进制战报的内容是不变的，因此为了提升效率，这类对象手动实现 DeepCopy 的效率是最高的(只拷贝会改变的字段)

Documentation

Overview

deepcopy-gen is a tool for auto-generating DeepCopy functions.

Given a list of input directories, it will generate DeepCopy and DeepCopyInto methods that efficiently perform a full deep-copy of each type. If these already exist (are predefined by the developer), they are used instead of generating new ones.

If interfaces are referenced in types, it is expected that corresponding DeepCopyInterfaceName methods exist, e.g. DeepCopyObject for runtime.Object. These can be predefined by the developer or generated through tags, see below. They must be added to the interfaces themselves manually, e.g.

type Object interface {
  ...
  DeepCopyObject() Object
}

All generation is governed by comment tags in the source. Any package may request DeepCopy generation by including a comment in the file-comments of a doc.go file, of the form:

// +deepcopy-gen=package

DeepCopy functions can be generated for individual types, rather than the entire package by specifying a comment on the type definion of the form:

// +deepcopy-gen=true

When generating for a whole package, individual types may opt out of DeepCopy generation by specifying a comment on the type definition of the form:

// +deepcopy-gen=false

Additional DeepCopyInterfaceName methods can be generated by specifying a comment on the type definition of the form:

// +deepcopy-gen:interfaces=k8s.io/kubernetes/runtime.Object,k8s.io/kubernetes/runtime.List

This leads to the generation of DeepCopyObject and DeepCopyList with the given interfaces as return types. We say that the tagged type implements deepcopy for the interfaces.

The deepcopy funcs for interfaces using "+deepcopy-gen:interfaces" use the pointer of the type as receiver. For those special cases where the non-pointer object should implement the interface, this can be done with:

// +deepcopy-gen:nonpointer-interfaces=true