schema: shared annotation interface for schema objects (#813)

2026-04-28 05:30:56 +03:00 · 2020-10-03 16:51:00 +03:00
parent a56b3b24d0
commit 1b5f51b827
9 changed files with 74 additions and 67 deletions
--- a/schema/edge/edge.go
+++ b/schema/edge/edge.go
@@ -6,28 +6,22 @@ package edge

 import (
 	"reflect"
-)

-// Annotation is used to attach arbitrary metadata to the edge object in codegen.
-// The object must be serializable to JSON raw value (e.g. struct, map or slice).
-// Template extensions can retrieve this metadata and use it inside their templates.
-type Annotation interface {
-	// Name defines the name of the annotation to be retrieved by the codegen.
-	Name() string
-}
+	"github.com/facebook/ent/schema"
+)

 // A Descriptor for edge configuration.
 type Descriptor struct {
-	Tag         string       // struct tag.
-	Type        string       // edge type.
-	Name        string       // edge name.
-	RefName     string       // ref name; inverse only.
-	Ref         *Descriptor  // edge reference; to/from of the same type.
-	Unique      bool         // unique edge.
-	Inverse     bool         // inverse edge.
-	Required    bool         // required on creation.
-	StorageKey  *StorageKey  // optional storage-key configuration.
-	Annotations []Annotation // edge annotations.
+	Tag         string              // struct tag.
+	Type        string              // edge type.
+	Name        string              // edge name.
+	RefName     string              // ref name; inverse only.
+	Ref         *Descriptor         // edge reference; to/from of the same type.
+	Unique      bool                // unique edge.
+	Inverse     bool                // inverse edge.
+	Required    bool                // required on creation.
+	StorageKey  *StorageKey         // optional storage-key configuration.
+	Annotations []schema.Annotation // edge annotations.
 }

 // To defines an association edge between two vertices.
@@ -105,7 +99,7 @@ func (b *assocBuilder) StorageKey(opts ...StorageOption) *assocBuilder {
 //			FieldName: "Pets",
 //		})
 //
-func (b *assocBuilder) Annotations(annotations ...Annotation) *assocBuilder {
+func (b *assocBuilder) Annotations(annotations ...schema.Annotation) *assocBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -161,7 +155,7 @@ func (b *inverseBuilder) Comment(string) *inverseBuilder {
 //			FieldName: "Owner",
 //		})
 //
-func (b *inverseBuilder) Annotations(annotations ...Annotation) *inverseBuilder {
+func (b *inverseBuilder) Annotations(annotations ...schema.Annotation) *inverseBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
--- a/schema/edge/edge_test.go
+++ b/schema/edge/edge_test.go
@@ -7,12 +7,12 @@ package edge_test
 import (
 	"testing"

-	"github.com/stretchr/testify/require"
-
 	"github.com/facebook/ent"
+	"github.com/facebook/ent/schema"
 	"github.com/facebook/ent/schema/edge"

 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )

 func TestEdge(t *testing.T) {
@@ -100,16 +100,16 @@ func TestAnnotations(t *testing.T) {
 	to := edge.To("user", User.Type).
 		Annotations(GQL{Field: "to"}).
 		Descriptor()
-	require.Equal(t, []edge.Annotation{GQL{Field: "to"}}, to.Annotations)
+	require.Equal(t, []schema.Annotation{GQL{Field: "to"}}, to.Annotations)
 	from := edge.From("user", User.Type).
 		Annotations(GQL{Field: "from"}).
 		Descriptor()
-	require.Equal(t, []edge.Annotation{GQL{Field: "from"}}, from.Annotations)
+	require.Equal(t, []schema.Annotation{GQL{Field: "from"}}, from.Annotations)
 	bidi := edge.To("following", User.Type).
 		Annotations(GQL{Field: "to"}).
 		From("followers").
 		Annotations(GQL{Field: "from"}).
 		Descriptor()
-	require.Equal(t, []edge.Annotation{GQL{Field: "from"}}, bidi.Annotations)
-	require.Equal(t, []edge.Annotation{GQL{Field: "to"}}, bidi.Ref.Annotations)
+	require.Equal(t, []schema.Annotation{GQL{Field: "from"}}, bidi.Annotations)
+	require.Equal(t, []schema.Annotation{GQL{Field: "to"}}, bidi.Ref.Annotations)
 }
--- a/schema/field/field.go
+++ b/schema/field/field.go
@@ -14,6 +14,8 @@ import (
 	"regexp"
 	"sort"
 	"time"
+
+	"github.com/facebook/ent/schema"
 )

 // String returns a new Field with type string.
@@ -276,7 +278,7 @@ func (b *stringBuilder) GoType(typ interface{}) *stringBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *stringBuilder) Annotations(annotations ...Annotation) *stringBuilder {
+func (b *stringBuilder) Annotations(annotations ...schema.Annotation) *stringBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -370,7 +372,7 @@ func (b *timeBuilder) GoType(typ interface{}) *timeBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *timeBuilder) Annotations(annotations ...Annotation) *timeBuilder {
+func (b *timeBuilder) Annotations(annotations ...schema.Annotation) *timeBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -461,7 +463,7 @@ func (b *boolBuilder) GoType(typ interface{}) *boolBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *boolBuilder) Annotations(annotations ...Annotation) *boolBuilder {
+func (b *boolBuilder) Annotations(annotations ...schema.Annotation) *boolBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -546,7 +548,7 @@ func (b *bytesBuilder) GoType(typ interface{}) *bytesBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *bytesBuilder) Annotations(annotations ...Annotation) *bytesBuilder {
+func (b *bytesBuilder) Annotations(annotations ...schema.Annotation) *bytesBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -628,7 +630,7 @@ func (b *jsonBuilder) SchemaType(types map[string]string) *jsonBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *jsonBuilder) Annotations(annotations ...Annotation) *jsonBuilder {
+func (b *jsonBuilder) Annotations(annotations ...schema.Annotation) *jsonBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -764,7 +766,7 @@ func (b *enumBuilder) SchemaType(types map[string]string) *enumBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *enumBuilder) Annotations(annotations ...Annotation) *enumBuilder {
+func (b *enumBuilder) Annotations(annotations ...schema.Annotation) *enumBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -869,7 +871,7 @@ func (b *uuidBuilder) SchemaType(types map[string]string) *uuidBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *uuidBuilder) Annotations(annotations ...Annotation) *uuidBuilder {
+func (b *uuidBuilder) Annotations(annotations ...schema.Annotation) *uuidBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -879,14 +881,6 @@ func (b *uuidBuilder) Descriptor() *Descriptor {
 	return b.desc
 }

-// Annotation is used to attach arbitrary metadata to the field object in codegen.
-// The object must be serializable to JSON raw value (e.g. struct, map or slice).
-// Template extensions can retrieve this metadata and use it inside their templates.
-type Annotation interface {
-	// Name defines the name of the annotation to be retrieved by the codegen.
-	Name() string
-}
-
 // A Descriptor for field configuration.
 type Descriptor struct {
 	Tag           string                  // struct tag.
@@ -904,7 +898,7 @@ type Descriptor struct {
 	Enums         []struct{ N, V string } // enum values.
 	Sensitive     bool                    // sensitive info string field.
 	SchemaType    map[string]string       // override the schema type.
-	Annotations   []Annotation            // field annotations.
+	Annotations   []schema.Annotation     // field annotations.
 	err           error
 }

--- a/schema/field/internal/gen.go
+++ b/schema/field/internal/gen.go
@@ -17,7 +17,7 @@ import (
 )

 func main() {
-	buf, err := ioutil.ReadFile("gen/numeric.tmpl")
+	buf, err := ioutil.ReadFile("internal/numeric.tmpl")
 	if err != nil {
 		log.Fatal("reading template file:", err)
 	}
--- a/schema/field/internal/numeric.tmpl
+++ b/schema/field/internal/numeric.tmpl
@@ -8,9 +8,11 @@ package field
 import (
 	"errors"
 	"reflect"
+
+	"github.com/facebook/ent/schema"
 )

-//go:generate go run gen/gen.go
+//go:generate go run internal/gen.go

 {{ range $t := $.Ints }}
 	{{ $title := title $t.String }}
@@ -182,7 +184,7 @@ func (b *{{ $builder }}) GoType(typ interface{}) *{{ $builder }} {
 //			Ordered: true,
 //		})
 //
-func (b *{{ $builder }}) Annotations(annotations ...Annotation) *{{ $builder }} {
+func (b *{{ $builder }}) Annotations(annotations ...schema.Annotation) *{{ $builder }} {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -341,7 +343,7 @@ func (b *{{ $builder }}) GoType(typ interface{}) *{{ $builder }} {
 //			Ordered: true,
 //		})
 //
-func (b *{{ $builder }}) Annotations(annotations ...Annotation) *{{ $builder }} {
+func (b *{{ $builder }}) Annotations(annotations ...schema.Annotation) *{{ $builder }} {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
--- a/schema/field/numeric.go
+++ b/schema/field/numeric.go
@@ -7,9 +7,11 @@ package field
 import (
 	"errors"
 	"reflect"
+
+	"github.com/facebook/ent/schema"
 )

-//go:generate go run gen/gen.go
+//go:generate go run internal/gen.go

 // Int returns a new Field with type int.
 func Int(name string) *intBuilder {
@@ -247,7 +249,7 @@ func (b *intBuilder) GoType(typ interface{}) *intBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *intBuilder) Annotations(annotations ...Annotation) *intBuilder {
+func (b *intBuilder) Annotations(annotations ...schema.Annotation) *intBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -387,7 +389,7 @@ func (b *uintBuilder) GoType(typ interface{}) *uintBuilder {
 //			Ordered: true,
 //		})
 //
-func (b *uintBuilder) Annotations(annotations ...Annotation) *uintBuilder {
+func (b *uintBuilder) Annotations(annotations ...schema.Annotation) *uintBuilder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -537,7 +539,7 @@ func (b *int8Builder) GoType(typ interface{}) *int8Builder {
 //			Ordered: true,
 //		})
 //
-func (b *int8Builder) Annotations(annotations ...Annotation) *int8Builder {
+func (b *int8Builder) Annotations(annotations ...schema.Annotation) *int8Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -687,7 +689,7 @@ func (b *int16Builder) GoType(typ interface{}) *int16Builder {
 //			Ordered: true,
 //		})
 //
-func (b *int16Builder) Annotations(annotations ...Annotation) *int16Builder {
+func (b *int16Builder) Annotations(annotations ...schema.Annotation) *int16Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -837,7 +839,7 @@ func (b *int32Builder) GoType(typ interface{}) *int32Builder {
 //			Ordered: true,
 //		})
 //
-func (b *int32Builder) Annotations(annotations ...Annotation) *int32Builder {
+func (b *int32Builder) Annotations(annotations ...schema.Annotation) *int32Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -987,7 +989,7 @@ func (b *int64Builder) GoType(typ interface{}) *int64Builder {
 //			Ordered: true,
 //		})
 //
-func (b *int64Builder) Annotations(annotations ...Annotation) *int64Builder {
+func (b *int64Builder) Annotations(annotations ...schema.Annotation) *int64Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -1127,7 +1129,7 @@ func (b *uint8Builder) GoType(typ interface{}) *uint8Builder {
 //			Ordered: true,
 //		})
 //
-func (b *uint8Builder) Annotations(annotations ...Annotation) *uint8Builder {
+func (b *uint8Builder) Annotations(annotations ...schema.Annotation) *uint8Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -1267,7 +1269,7 @@ func (b *uint16Builder) GoType(typ interface{}) *uint16Builder {
 //			Ordered: true,
 //		})
 //
-func (b *uint16Builder) Annotations(annotations ...Annotation) *uint16Builder {
+func (b *uint16Builder) Annotations(annotations ...schema.Annotation) *uint16Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -1407,7 +1409,7 @@ func (b *uint32Builder) GoType(typ interface{}) *uint32Builder {
 //			Ordered: true,
 //		})
 //
-func (b *uint32Builder) Annotations(annotations ...Annotation) *uint32Builder {
+func (b *uint32Builder) Annotations(annotations ...schema.Annotation) *uint32Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -1547,7 +1549,7 @@ func (b *uint64Builder) GoType(typ interface{}) *uint64Builder {
 //			Ordered: true,
 //		})
 //
-func (b *uint64Builder) Annotations(annotations ...Annotation) *uint64Builder {
+func (b *uint64Builder) Annotations(annotations ...schema.Annotation) *uint64Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -1706,7 +1708,7 @@ func (b *float64Builder) GoType(typ interface{}) *float64Builder {
 //			Ordered: true,
 //		})
 //
-func (b *float64Builder) Annotations(annotations ...Annotation) *float64Builder {
+func (b *float64Builder) Annotations(annotations ...schema.Annotation) *float64Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
@@ -1852,7 +1854,7 @@ func (b *float32Builder) GoType(typ interface{}) *float32Builder {
 //			Ordered: true,
 //		})
 //
-func (b *float32Builder) Annotations(annotations ...Annotation) *float32Builder {
+func (b *float32Builder) Annotations(annotations ...schema.Annotation) *float32Builder {
 	b.desc.Annotations = append(b.desc.Annotations, annotations...)
 	return b
 }
--- a/schema/mixin/mixin.go
+++ b/schema/mixin/mixin.go
@@ -8,7 +8,7 @@ import (
 	"time"

 	"github.com/facebook/ent"
-	"github.com/facebook/ent/schema/edge"
+	"github.com/facebook/ent/schema"
 	"github.com/facebook/ent/schema/field"
 )

@@ -82,18 +82,18 @@ func (Time) Fields() []ent.Field {
 var _ ent.Mixin = (*Time)(nil)

 // AnnotateFields adds field annotations to underlying mixin fields.
-func AnnotateFields(m ent.Mixin, annotations ...field.Annotation) ent.Mixin {
+func AnnotateFields(m ent.Mixin, annotations ...schema.Annotation) ent.Mixin {
 	return fieldAnnotator{Mixin: m, annotations: annotations}
 }

 // AnnotateEdges adds edge annotations to underlying mixin edges.
-func AnnotateEdges(m ent.Mixin, annotations ...edge.Annotation) ent.Mixin {
+func AnnotateEdges(m ent.Mixin, annotations ...schema.Annotation) ent.Mixin {
 	return edgeAnnotator{Mixin: m, annotations: annotations}
 }

 type fieldAnnotator struct {
 	ent.Mixin
-	annotations []field.Annotation
+	annotations []schema.Annotation
 }

 func (a fieldAnnotator) Fields() []ent.Field {
@@ -107,7 +107,7 @@ func (a fieldAnnotator) Fields() []ent.Field {

 type edgeAnnotator struct {
 	ent.Mixin
-	annotations []edge.Annotation
+	annotations []schema.Annotation
 }

 func (a edgeAnnotator) Edges() []ent.Edge {
--- a/schema/mixin/mixin_test.go
+++ b/schema/mixin/mixin_test.go
@@ -8,8 +8,8 @@ import (
 	"testing"

 	"github.com/facebook/ent"
+	"github.com/facebook/ent/schema"
 	"github.com/facebook/ent/schema/edge"
-	"github.com/facebook/ent/schema/field"
 	"github.com/facebook/ent/schema/mixin"

 	"github.com/stretchr/testify/assert"
@@ -51,7 +51,7 @@ type annotation string
 func (annotation) Name() string { return "" }

 func TestAnnotateFields(t *testing.T) {
-	annotations := []field.Annotation{
+	annotations := []schema.Annotation{
 		annotation("foo"),
 		annotation("bar"),
 		annotation("baz"),
@@ -82,7 +82,7 @@ func (TestSchema) Edges() []ent.Edge {
 }

 func TestAnnotateEdges(t *testing.T) {
-	annotations := []edge.Annotation{
+	annotations := []schema.Annotation{
 		annotation("foo"),
 		annotation("bar"),
 		annotation("baz"),
--- a/schema/schema.go
+++ b/schema/schema.go
@@ -0,0 +1,15 @@
+// Copyright 2019-present Facebook Inc. All rights reserved.
+// This source code is licensed under the Apache 2.0 license found
+// in the LICENSE file in the root directory of this source tree.
+
+package schema
+
+// Annotation is used to attach arbitrary metadata to the schema objects in codegen.
+// The object must be serializable to JSON raw value (e.g. struct, map or slice).
+//
+// Template extensions can retrieve this metadata and use it inside their templates.
+// Read more about it in ent website: https://entgo.io/docs/templates/#annotations.
+type Annotation interface {
+	// Name defines the name of the annotation to be retrieved by the codegen.
+	Name() string
+}