Variables

A variable is a storage location for holding a value. The set of permissible values is determined by the variable’s type.

A variable declaration or, for function parameters and results, the signature of a function declaration or function literal reserves storage for a named variable.

Calling the built-in function new or taking the address of a composite literal allocates storage for a variable at run time. Such an anonymous variable is referred to via a (possibly implicit) pointer indirection.

Structured variables of array, slice, and struct types have elements and fields that may be addressed individually. Each such element acts like a variable.

The static type (or just type) 【靜態類型或類型】of a variable is the type given in its declaration, the type provided in the new call or composite literal, or the type of an element of a structured variable.

Variables of interface type also have a distinct dynamic type【動態類型】, which is the (non-interface) type of the value assigned to the variable at run time (unless the value is the predeclared identifier nil, which has no type). The dynamic type may vary during execution but values stored in interface variables are always assignable to the static type of the variable.

var x interface{}  // x is nil and has static type interface{}
var v *T           // v has value nil, static type *T
x = 42             // x has value 42 and dynamic type int
x = v              // x has value (*T)(nil) and dynamic type *T

A variable’s value is retrieved by referring to the variable in an expression; it is the most recent value assigned to the variable. If a variable has not yet been assigned a value, its value is the zero value for its type.

Types

A type determines a set of values together with operations and methods specific to those values. A type may be denoted by a type name, if it has one, which must be followed by type arguments if the type is generic. A type may also be specified using a type literal, which composes a type from existing types.

Type     = TypeName [ TypeArgs ] | TypeLit | "(" Type ")" .
TypeName = identifier | QualifiedIdent .
TypeArgs = "[" TypeList [ "," ] "]" .
TypeList = Type { "," Type } .
TypeLit  = ArrayType | StructType | PointerType | FunctionType | InterfaceType |SliceType | MapType | ChannelType .

The language predeclares certain type names. Others are introduced with type declarations or type parameter lists. Composite types—array, struct, pointer, function, interface, slice, map, and channel types—may be constructed using type literals.

Predeclared types, defined types, and type parameters are called named types【命名類型】. An alias denotes a named type if the type given in the alias declaration is a named type.【注意：類型字面值不是命名類型，比如[]int、struct{} 等是未命名類型】

Boolean types

A boolean type represents the set of Boolean truth values denoted by the predeclared constants true and false. The predeclared boolean type is bool; it is a defined type.

Numeric types

An integer, floating-point, or complex type represents the set of integer, floating-point, or complex values, respectively. They are collectively called numeric types. The predeclared architecture-independent numeric types are:

uint8       the set of all unsigned  8-bit integers (0 to 255)
uint16      the set of all unsigned 16-bit integers (0 to 65535)
uint32      the set of all unsigned 32-bit integers (0 to 4294967295)
uint64      the set of all unsigned 64-bit integers (0 to 18446744073709551615)int8        the set of all signed  8-bit integers (-128 to 127)
int16       the set of all signed 16-bit integers (-32768 to 32767)
int32       the set of all signed 32-bit integers (-2147483648 to 2147483647)
int64       the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)float32     the set of all IEEE 754 32-bit floating-point numbers
float64     the set of all IEEE 754 64-bit floating-point numberscomplex64   the set of all complex numbers with float32 real and imaginary parts
complex128  the set of all complex numbers with float64 real and imaginary partsbyte        alias for uint8
rune        alias for int32

The value of an n-bit integer is n bits wide and represented using two’s complement arithmetic.【二進制補碼表示】

---

• 現代計算機普遍用 二進制補碼 表示有符號整數（如 Go 的 int、int32 等），其規則如下：

  • 最高位為符號位：0 表示正數，1 表示負數。

  • 正數：直接存儲其二進制形式（如 5 的 8 位補碼是 00000101）。

  • 負數：

    1. 先取絕對值的二進制表示。
    2. 按位取反（0 變 1，1 變 0）。
    3. 加 1。

    • 例如，-5 的 8 位補碼計算：

      5 的二進制 → 00000101
      按位取反   → 11111010
      加 1       → 11111011 （即 -5 的補碼）
      

---

There is also a set of predeclared integer types with implementation-specific sizes:

uint     either 32 or 64 bits
int      same size as uint
uintptr  an unsigned integer large enough to store the uninterpreted bits of a pointer value

To avoid portability issues all numeric types are defined types 【定義的類型是一個新的類型】and thus distinct except byte, which is an alias for uint8, and rune, which is an alias for int32. Explicit conversions are required when different numeric types are mixed in an expression or assignment. For instance, int32 and int are not the same type even though they may have the same size on a particular architecture.

byte類型和uint8類型是相同的類型，rune類型和int32類型是相同的類型，其他的數值類型都不相同，在表達式或賦值中需要顯示的轉換。

String types

A string type represents the set of string values. A string value is a (possibly empty) sequence of bytes. The number of bytes is called the length of the string and is never negative. Strings are immutable: once created, it is impossible to change the contents of a string【字符串是不可變的】. The predeclared string type is string; it is a defined type.

The length of a string s can be discovered using the built-in function len. The length is a compile-time constant if the string is a constant. A string’s bytes can be accessed by integer indices 0 through len(s)-1. It is illegal to take the address of such an element; if s[i] is the i’th byte of a string, &s[i] is invalid.

Array types

An array is a numbered sequence of elements of a single type, called the element type. The number of elements is called the length of the array and is never negative.

ArrayType   = "[" ArrayLength "]" ElementType .
ArrayLength = Expression .
ElementType = Type .

The length is part of the array’s type; it must evaluate to a non-negative constant representable by a value of type int. The length of array a can be discovered using the built-in function len. The elements can be addressed by integer indices 0 through len(a)-1. Array types are always one-dimensional but may be composed to form multi-dimensional types.

[32]byte
[2*N] struct { x, y int32 }
[1000]*float64
[3][5]int
[2][2][2]float64  // same as [2]([2]([2]float64))

An array type T may not have an element of type T, or of a type containing T as a component, directly or indirectly, if those containing types are only array or struct types.【注意！】

// invalid array types
type (T1 [10]T1                 // element type of T1 is T1T2 [10]struct{ f T2 }     // T2 contains T2 as component of a structT3 [10]T4                 // T3 contains T3 as component of a struct in T4T4 struct{ f T3 }         // T4 contains T4 as component of array T3 in a struct
)// valid array types
type (T5 [10]*T5                // T5 contains T5 as component of a pointerT6 [10]func() T6          // T6 contains T6 as component of a function typeT7 [10]struct{ f []T7 }   // T7 contains T7 as component of a slice in a struct
)

Slice types

A slice is a descriptor for a contiguous segment of an underlying array and provides access to a numbered sequence of elements from that array. A slice type denotes the set of all slices of arrays of its element type. The number of elements is called the length of the slice and is never negative. The value of an uninitialized slice is nil.

SliceType = "[" "]" ElementType .

The length of a slice s can be discovered by the built-in function len; unlike with arrays it may change during execution. The elements can be addressed by integer indices 0 through len(s)-1. The slice index of a given element may be less than the index of the same element in the underlying array.

A slice, once initialized, is always associated with an underlying array that holds its elements. A slice therefore shares storage with its array and with other slices of the same array; by contrast, distinct arrays always represent distinct storage.

The array underlying a slice may extend past the end of the slice. The capacity 【容量】is a measure of that extent: it is the sum of the length of the slice and the length of the array beyond the slice; a slice of length up to that capacity can be created by slicing a new one from the original slice. The capacity of a slice a can be discovered using the built-in function cap(a).

A new, initialized slice value for a given element type T may be made using the built-in function make, which takes a slice type and parameters specifying the length and optionally the capacity. A slice created with make always allocates a new, hidden array to which the returned slice value refers. That is, executing

make([]T, length, capacity)

produces the same slice as allocating an array and slicing it, so these two expressions are equivalent:

make([]int, 50, 100)
new([100]int)[0:50]

Like arrays, slices are always one-dimensional but may be composed to construct higher-dimensional objects. With arrays of arrays, the inner arrays are, by construction, always the same length; however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. Moreover, the inner slices must be initialized individually.

Struct types

A struct is a sequence of named elements, called fields, each of which has a name and a type. Field names may be specified explicitly (IdentifierList) or implicitly (EmbeddedField). Within a struct, non-blank field names must be unique.

StructType    = "struct" "{" { FieldDecl ";" } "}" .
FieldDecl     = (IdentifierList Type | EmbeddedField) [ Tag ] .
EmbeddedField = [ "*" ] TypeName [ TypeArgs ] .
Tag           = string_lit .

// An empty struct.
struct {}// A struct with 6 fields.
struct {x, y intu float32_ float32  // paddingA *[]intF func()
}

A field declared with a type but no explicit field name is called an embedded field【嵌入字段】. An embedded field must be specified as a type name T or as a pointer to a non-interface type name *T, and T itself may not be a pointer type or type parameter. The unqualified type name acts as the field name.

// A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4
struct {T1        // field name is T1*T2       // field name is T2P.T3      // field name is T3*P.T4     // field name is T4x, y int  // field names are x and y
}

The following declaration is illegal because field names must be unique in a struct type:

struct {T     // conflicts with embedded field *T and *P.T*T    // conflicts with embedded field T and *P.T*P.T  // conflicts with embedded field T and *T
}

A field or method f of an embedded field in a struct x is called promoted【提升】 if x.f is a legal selector that denotes that field or method f.

---

For a primary expression x that is not a package name, the selector expression

x.f

denotes the field or method f of the value x (or sometimes *x; see below). The identifier f is called the (field or method) selector【選擇器】; it must not be the blank identifier. The type of the selector expression is the type of f. If x is a package name, see the section on qualified identifiers.

A selector f may denote a field or method f of a type T, or it may refer to a field or method f of a nested embedded field of T.

The number of embedded fields traversed to reach f is called its depth in T. The depth of a field or method f declared in T is zero. The depth of a field or method f declared in an embedded field A in T is the depth of f in A plus one.

The following rules apply to selectors:

1. For a value x of type T or *T where T is not a pointer or interface type, x.f denotes the field or method at the shallowest depth in T where there is such an f. If there is not exactly one f with shallowest depth, the selector expression is illegal.
2. For a value x of type I where I is an interface type, x.f denotes the actual method with name f of the dynamic value of x. If there is no method with name f in the method set of I, the selector expression is illegal.
3. As an exception, if the type of x is a defined pointer type and (*x).f is a valid selector expression denoting a field (but not a method), x.f is shorthand for (*x).f.
4. In all other cases, x.f is illegal.
5. If x is of pointer type and has the value nil and x.f denotes a struct field, assigning to or evaluating x.f causes a run-time panic.
6. If x is of interface type and has the value nil, calling or evaluating the method x.f causes a run-time panic.

---

Promoted fields 【提升的字段】act like ordinary fields of a struct except that they cannot be used as field names in composite literals of the struct.

---

提升字段（Promoted fields）指通過結構體嵌入（embedded fields）機制，將內部嵌套結構體的字段或方法自動提升到外層結構體的語法特性。其核心規則是：

1. 類似普通字段
   提升字段在外層結構體中可直接訪問，就像屬于外層結構體自身定義的字段一樣：

   type Address struct { City string }
   type User struct {Name stringAddress // 嵌入字段（Address 的字段會被提升）
   }u := User{}
   u.City = "Beijing" // 直接訪問提升字段（等同于 u.Address.City）
   

2. 復合字面量中的限制
   提升字段不能直接用作復合字面量（struct literal）的字段名，必須通過嵌入類型名顯式指定：

   // 錯誤寫法（編譯報錯）
   u := User{Name: "Alice",City: "Shanghai", // 錯誤：City 是提升字段，不能直接使用
   }// 正確寫法
   u := User{Name: "Alice",Address: Address{City: "Shanghai"}, // 必須通過嵌入類型名初始化
   }
   

---

結構體類型的方法集

Given a struct type S and a type name T, promoted methods are included in the method set of the struct as follows:

• ? If S contains an embedded field T, the method sets【方法集】 of S and *S both include promoted methods with receiver T. The method set of *S also includes promoted methods with receiver *T.
• ? If S contains an embedded field *T, the method sets of S and *S both include promoted methods with receiver T or *T.

A field declaration may be followed by an optional string literal tag, which becomes an attribute for all the fields in the corresponding field declaration. An empty tag string is equivalent to an absent tag. The tags are made visible through a reflection interface and take part in type identity for structs but are otherwise ignored.

struct {x, y float64 ""  // an empty tag string is like an absent tagname string  "any string is permitted as a tag"_    [4]byte "ceci n'est pas un champ de structure"
}// A struct corresponding to a TimeStamp protocol buffer.
// The tag strings define the protocol buffer field numbers;
// they follow the convention outlined by the reflect package.
struct {microsec  uint64 `protobuf:"1"`serverIP6 uint64 `protobuf:"2"`
}

A struct type T may not contain a field of type T, or of a type containing T as a component, directly or indirectly, if those containing types are only array or struct types.

// invalid struct types
type (T1 struct{ T1 }            // T1 contains a field of T1T2 struct{ f [10]T2 }      // T2 contains T2 as component of an arrayT3 struct{ T4 }            // T3 contains T3 as component of an array in struct T4T4 struct{ f [10]T3 }      // T4 contains T4 as component of struct T3 in an array
)// valid struct types
type (T5 struct{ f *T5 }         // T5 contains T5 as component of a pointerT6 struct{ f func() T6 }   // T6 contains T6 as component of a function typeT7 struct{ f [10][]T7 }    // T7 contains T7 as component of a slice in an array
)

Pointer types

A pointer type denotes the set of all pointers to variables of a given type, called the base type of the pointer. The value of an uninitialized pointer is nil.

PointerType = "*" BaseType .
BaseType    = Type .

*Point
*[4]int

Function types

A function type denotes the set of all functions with the same parameter and result types. The value of an uninitialized variable of function type is nil.

FunctionType  = "func" Signature .
Signature     = Parameters [ Result ] .
Result        = Parameters | Type .
Parameters    = "(" [ ParameterList [ "," ] ] ")" .
ParameterList = ParameterDecl { "," ParameterDecl } .
ParameterDecl = [ IdentifierList ] [ "..." ] Type .

Within a list of parameters or results, the names (IdentifierList) must either all be present or all be absent. If present, each name stands for one item (parameter or result) of the specified type and all non-blank names in the signature must be unique. If absent, each type stands for one item of that type. Parameter and result lists are always parenthesized except that if there is exactly one unnamed result it may be written as an unparenthesized type.【如果返回結果只有一個類型，可以省略掉括號】

The final incoming parameter in a function signature may have a type prefixed with .... A function with such a parameter is called variadic【變參函數】 and may be invoked with zero or more arguments for that parameter.

func()
func(x int) int
func(a, _ int, z float32) bool
func(a, b int, z float32) (bool)
func(prefix string, values ...int)
func(a, b int, z float64, opt ...interface{}) (success bool)
func(int, int, float64) (float64, *[]int)
func(n int) func(p *T)

Interface types

An interface type defines a type set. A variable of interface type can store a value of any type that is in the type set of the interface. Such a type is said to implement the interface. The value of an uninitialized variable of interface type is nil.

InterfaceType  = "interface" "{" { InterfaceElem ";" } "}" .
InterfaceElem  = MethodElem | TypeElem .
MethodElem     = MethodName Signature .
MethodName     = identifier .
TypeElem       = TypeTerm { "|" TypeTerm } .
TypeTerm       = Type | UnderlyingType .
UnderlyingType = "~" Type .

An interface type is specified by a list of interface elements. An interface element is either a method or a type element, where a type element is a union of one or more type terms. A type term is either a single type or a single underlying type.

Basic interfaces

In its most basic form an interface specifies a (possibly empty) list of methods. The type set defined by such an interface is the set of types which implement all of those methods, and the corresponding method set consists exactly of the methods specified by the interface. Interfaces whose type sets can be defined entirely by a list of methods are called basic interfaces.

// A simple File interface.
interface {Read([]byte) (int, error)Write([]byte) (int, error)Close() error
}

The name of each explicitly specified method must be unique and not blank.

interface {String() stringString() string  // illegal: String not unique_(x int)         // illegal: method must have non-blank name
}

More than one type may implement an interface. For instance, if two types S1 and S2 have the method set

func (p T) Read(p []byte) (n int, err error)
func (p T) Write(p []byte) (n int, err error)
func (p T) Close() error

(where T stands for either S1 or S2) then the File interface is implemented by both S1 and S2, regardless of what other methods S1 and S2 may have or share.

Every type that is a member of the type set of an interface implements that interface. Any given type may implement several distinct interfaces. For instance, all types implement the empty interface which stands for the set of all (non-interface) types:

interface{}

For convenience, the predeclared type any is an alias for the empty interface. [Go 1.18]

Similarly, consider this interface specification, which appears within a type declaration to define an interface called Locker:

type Locker interface {Lock()Unlock()
}

If S1 and S2 also implement

func (p T) Lock() { … }
func (p T) Unlock() { … }

they implement the Locker interface as well as the File interface.

Embedded interfaces

In a slightly more general form an interface T may use a (possibly qualified) interface type name E as an interface element. This is called embedding interface E in T [Go 1.14]. The type set of T is the intersection【交集】 of the type sets defined by T’s explicitly declared methods and the type sets of T’s embedded interfaces. In other words, the type set of T is the set of all types that implement all the explicitly declared methods of T and also all the methods of E [Go 1.18].

type Reader interface {Read(p []byte) (n int, err error)Close() error
}type Writer interface {Write(p []byte) (n int, err error)Close() error
}// ReadWriter's methods are Read, Write, and Close.
type ReadWriter interface {Reader  // includes methods of Reader in ReadWriter's method setWriter  // includes methods of Writer in ReadWriter's method set
}

When embedding interfaces, methods with the same names must have identical signatures.

type ReadCloser interface {Reader   // includes methods of Reader in ReadCloser's method setClose()  // illegal: signatures of Reader.Close and Close are different
}

General interfaces【泛型接口】

In their most general form, an interface element may also be an arbitrary type term T, or a term of the form ~T specifying the underlying type T, or a union of terms t1|t2|…|tn [Go 1.18]. Together with method specifications, these elements enable the precise definition of an interface’s type set as follows:

• The type set of the empty interface is the set of all non-interface types.
• The type set of a non-empty interface is the intersection of the type sets of its interface elements.
• The type set of a method specification is the set of all non-interface types whose method sets include that method.
• The type set of a non-interface type term is the set consisting of just that type.
• The type set of a term of the form ~T is the set of all types whose underlying type is T.
• The type set of a union of terms t1|t2|…|tn is the union of the type sets of the terms.

The quantification “the set of all non-interface types” refers not just to all (non-interface) types declared in the program at hand, but all possible types in all possible programs, and hence is infinite.

Similarly, given the set of all non-interface types that implement a particular method, the intersection of the method sets of those types will contain exactly that method, even if all types in the program at hand always pair that method with another method.

By construction, an interface’s type set never contains an interface type.

任何接口的類型集合中，永遠不會包含其他接口類型（即接口不能直接作為其他接口的實現類型）。

// An interface representing only the type int.
interface {int
}// An interface representing all types with underlying type int.
interface {~int
}// An interface representing all types with underlying type int that implement the String method.
interface {~intString() string
}// An interface representing an empty type set: there is no type that is both an int and a string.
interface {intstring
}

In a term of the form ~T, the underlying type【底層類型】 of T must be itself, and T cannot be an interface.

type MyInt intinterface {~[]byte  // the underlying type of []byte is itself~MyInt   // illegal: the underlying type of MyInt is not MyInt~error   // illegal: error is an interface
}

Union elements denote unions of type sets:

// The Float interface represents all floating-point types
// (including any named types whose underlying types are
// either float32 or float64).
type Float interface {~float32 | ~float64
}

The type T in a term of the form T or ~T cannot be a type parameter, and the type sets of all non-interface terms must be pairwise disjoint (the pairwise intersection of the type sets must be empty). Given a type parameter P:

interface {P                // illegal: P is a type parameter。但是[]P 是合法的！int | ~P         // illegal: P is a type parameter~int | MyInt     // illegal: the type sets for ~int and MyInt are not disjoint (~int includes MyInt)float32 | Float  // overlapping type sets but Float is an interface
}

Implementation restriction: A union (with more than one term) cannot contain the predeclared identifier comparable or interfaces that specify methods, or embed comparable or interfaces that specify methods.

Interfaces that are not basic may only be used as type constraints【類型約束】, or as elements of other interfaces used as constraints. They cannot be the types of values or variables, or components of other, non-interface types.

不是基本接口的接口只能用作類型約束！

var x Float                     // illegal: Float is not a basic interfacevar x interface{} = Float(nil)  // illegaltype Floatish struct {f Float                 // illegal
}

An interface type T may not embed a type element that is, contains, or embeds T, directly or indirectly.

// illegal: Bad may not embed itself
type Bad interface {Bad
}// illegal: Bad1 may not embed itself using Bad2
type Bad1 interface {Bad2
}
type Bad2 interface {Bad1
}// illegal: Bad3 may not embed a union containing Bad3
type Bad3 interface {~int | ~string | Bad3
}// illegal: Bad4 may not embed an array containing Bad4 as element type
type Bad4 interface {[10]Bad4
}

Implementing an interface【實現一個接口】

A type T implements an interface I if

• ? T is not an interface and is an element of the type set of I; or
• ? T is an interface and the type set of T is a subset of the type set of I.

A value of type T implements an interface if T implements the interface.

Map types

A map is an unordered group of elements of one type, called the element type, indexed by a set of unique keys of another type, called the key type. The value of an uninitialized map is nil.

MapType = "map" "[" KeyType "]" ElementType .
KeyType = Type .

The comparison operators == and != must be fully defined for operands of the key type; thus the key type must not be a function, map, or slice. If the key type is an interface type, these comparison operators must be defined for the dynamic key values; failure will cause a run-time panic.

map[string]int
map[*T]struct{ x, y float64 }
map[string]interface{}

The number of map elements is called its length. For a map m, it can be discovered using the built-in function len and may change during execution. Elements may be added during execution using assignments and retrieved with index expressions; they may be removed with the delete and clear built-in function.

A new, empty map value is made using the built-in function make, which takes the map type and an optional capacity hint as arguments:

make(map[string]int)
make(map[string]int, 100)

The initial capacity does not bound its size: maps grow to accommodate the number of items stored in them, with the exception of nil maps. A nil map is equivalent to an empty map except that no elements may be added.

Channel types

A channel provides a mechanism for concurrently executing functions to communicate by sending and receiving values of a specified element type. The value of an uninitialized channel is nil.

ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType .

The optional <- operator specifies the channel direction, send or receive. If a direction is given, the channel is directional, otherwise it is bidirectional.

A channel may be constrained only to send or only to receive by assignment or explicit conversion.

chan T          // can be used to send and receive values of type T
chan<- float64  // can only be used to send float64s
<-chan int      // can only be used to receive ints

The <- operator associates with the leftmost chan possible:

chan<- chan int    // same as chan<- (chan int)
chan<- <-chan int  // same as chan<- (<-chan int)
<-chan <-chan int  // same as <-chan (<-chan int)
chan (<-chan int)

A new, initialized channel value can be made using the built-in function make, which takes the channel type and an optional capacity as arguments:

make(chan int, 100)

The capacity, in number of elements, sets the size of the buffer in the channel. If the capacity is zero or absent, the channel is unbuffered and communication succeeds only when both a sender and receiver are ready. Otherwise, the channel is buffered and communication succeeds without blocking if the buffer is not full (sends) or not empty (receives). A nil channel is never ready for communication.

A channel may be closed with the built-in function close. The multi-valued assignment form of the receive operator reports whether a received value was sent before the channel was closed.

A single channel may be used in send statements, receive operations, and calls to the built-in functions cap and len by any number of goroutines without further synchronization. Channels act as first-in-first-out queues. For example, if one goroutine sends values on a channel and a second goroutine receives them, the values are received in the order sent.