Go Reference Β· Concepts
Go exported identifiers
Reference for Go exported and unexported names: the capital-letter rule, struct fields and methods, JSON and reflection effects, internal packages and Unicode edge cases.
Go has no public or private keyword. Whether a name can be used from another package depends on one thing: its first character. If it is an upper-case Unicode letter, the identifier is exported and visible to every package that imports yours. Anything else is unexported and can be used only inside its own package.
The rule covers package-level constants, variables, types and functions, and also struct fields and methods. The unit of privacy is the package, not the type, so two types in the same package see each other's unexported fields. A package can also be hidden from outsiders by placing it under an internal directory.
type Account struct { Owner string // exported field balance int // unexported field } func (a *Account) Balance() int { return a.balance } // exported method func audit(a *Account) {} // unexported function
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input Β· what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input Β· what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
An identifier is exported when both conditions hold:
- The first character is a Unicode upper-case letter (category
Lu). - The identifier is declared in the package block, or it is a field name or a method name.
Local variables, parameters and labels are never exported, whatever they are called.
| Declaration | Visible to other packages when the name... |
|---|---|
| Function, type, constant, variable | starts with an upper-case letter |
| Struct field | starts with an upper-case letter (and the struct type itself is reachable) |
| Method | starts with an upper-case letter |
| Interface method | starts with an upper-case letter. An interface with an unexported method cannot be implemented outside its package. |
| Embedded field | its name is the type name; the same capitalization rule applies |
| Package name | not covered: package names are lower-case by convention |
Errors and edge cases:
- Using an unexported name from another package gives
undefined: pkg.nameorcannot refer to unexported name pkg.name. - A struct literal in another package cannot set an unexported field (
unknown field). If a struct has any unexported field, positional literals likepkg.T{1, 2}also fail there. - Scripts without cased letters (Chinese, Japanese, Arabic, ...) have no upper case, so such names are never exported. Prefix them with a Latin capital if they must be.
_is not a letter that has a case, so_Foois unexported.
Usage notes
- Packages like
encoding/json,encoding/xml,text/templateanddatabase/sqlwork through reflection and can only touch exported fields. A silently empty JSON field is nearly always a lower-case field name. - Export the least you can. Anything exported is part of your public API and a compatibility promise. Start unexported and open things up when callers need them.
- Hide implementations behind exported interfaces. Return an interface (or an exported type with unexported fields) and provide methods. Callers then cannot depend on your internals.
- Seal an interface by adding an unexported method to it. Types from other packages can use the interface but not implement it.
internal/directories. A package ata/b/internal/ccan be imported only by code rooted ata/b. The go command enforces this, which gives you package-level privacy between your own packages.- Same package means same access. Tests in
package foo(notfoo_test) can use unexported names; black-box tests inpackage foo_testsee only the exported API. - Doc comments.
go docand pkg.go.dev list only exported names. The convention is to start a doc comment with the name it describes.
Related
- Struct embedding, Method sets, JSON struct tags, package, import
- Lessons: Packages, Structs, Project Layout