八种常见组合

// Package construction demonstrates functional options for optional configuration.
package construction

import (
	"net"
	"strconv"
)

// Config contains the settings used by Server.
type Config struct {
	Host   string
	Port   int
	Secure bool
}

// Option changes one part of a Server configuration.
type Option func(*Config)

// WithHost configures the listening host.
func WithHost(host string) Option {
	return func(config *Config) {
		config.Host = host
	}
}

// WithPort configures the listening port.
func WithPort(port int) Option {
	return func(config *Config) {
		config.Port = port
	}
}

// WithSecure configures whether the server uses a secure transport.
func WithSecure(secure bool) Option {
	return func(config *Config) {
		config.Secure = secure
	}
}

// Server is a configured endpoint. Its configuration is immutable after construction.
type Server struct {
	config Config
}

// NewServer constructs a Server with useful defaults and optional overrides.
func NewServer(options ...Option) *Server {
	config := Config{Host: "127.0.0.1", Port: 8080}
	for _, option := range options {
		if option != nil {
			option(&config)
		}
	}
	return &Server{config: config}
}

// Config returns a copy of the server configuration.
func (s *Server) Config() Config {
	return s.config
}

// Address returns the host:port endpoint, including correct IPv6 formatting.
func (s *Server) Address() string {
	return net.JoinHostPort(s.config.Host, strconv.Itoa(s.config.Port))
}

// Package interfaces demonstrates consumer-defined, minimal interfaces.
package interfaces

// Product is the value returned by a Catalog.
type Product struct {
	Name       string
	PriceCents int
}

// Catalog is the only behavior needed by the pricing functions.
type Catalog interface {
	Find(name string) (Product, bool)
}

// CatalogFunc adapts a function to Catalog, avoiding a one-method struct in tests
// and small integrations.
type CatalogFunc func(name string) (Product, bool)

// Find implements Catalog.
func (f CatalogFunc) Find(name string) (Product, bool) {
	return f(name)
}

// PriceOf looks up one product through the smallest useful interface.
func PriceOf(catalog Catalog, name string) (int, bool) {
	if catalog == nil {
		return 0, false
	}
	product, ok := catalog.Find(name)
	if !ok {
		return 0, false
	}
	return product.PriceCents, true
}

// Total adds the prices of all requested products. It returns no partial total
// when any product is missing.
func Total(catalog Catalog, names []string) (int, bool) {
	if catalog == nil {
		return 0, false
	}

	total := 0
	for _, name := range names {
		product, ok := catalog.Find(name)
		if !ok {
			return 0, false
		}
		total += product.PriceCents
	}
	return total, true
}

// Package errors demonstrates sentinel categories, wrapping, and typed details.
package errors

import (
	"errors"
	"fmt"
)

// ErrNotFound is the stable category callers can inspect with errors.Is.
var ErrNotFound = errors.New("item not found")

// NotFoundError carries the key that was not present while remaining in the
// ErrNotFound category.
type NotFoundError struct {
	Key string
}

// Error implements error.
func (e *NotFoundError) Error() string {
	return fmt.Sprintf("item %q not found", e.Key)
}

// Unwrap makes errors.Is and errors.As work through wrapping layers.
func (e *NotFoundError) Unwrap() error {
	return ErrNotFound
}

// Lookup finds a value or returns a typed, classifiable not-found error.
func Lookup(items map[string]string, key string) (string, error) {
	value, ok := items[key]
	if !ok {
		return "", &NotFoundError{Key: key}
	}
	return value, nil
}

// Load adds operation context while preserving the underlying error identity.
func Load(items map[string]string, key string) (string, error) {
	value, err := Lookup(items, key)
	if err != nil {
		return "", fmt.Errorf("load %q: %w", key, err)
	}
	return value, nil
}

package ownership

import (
	"errors"
	"io"
)

// ReadOwned opens one reader, reads its contents, and closes it before returning.
// The returned error preserves both a read failure and a close failure.
func ReadOwned(open func() (io.ReadCloser, error)) (data []byte, err error) {
	reader, err := open()
	if err != nil {
		return nil, err
	}
	defer func() {
		err = errors.Join(err, reader.Close())
	}()
	return io.ReadAll(reader)
}

// Package ownership demonstrates a single-owner mutable queue and an explicit
// move-like Drain operation.
package ownership

// Queue is intended to be used by one goroutine at a time. Its zero value is
// ready to use; use shared-map (or another synchronization boundary) when
// multiple goroutines need shared mutable state.
type Queue struct {
	items []string
}

// NewQueue creates a queue with an optional initial capacity.
func NewQueue(capacity int) *Queue {
	if capacity < 0 {
		capacity = 0
	}
	return &Queue{items: make([]string, 0, capacity)}
}

// Push adds an item to the queue owned by q.
func (q *Queue) Push(item string) {
	q.items = append(q.items, item)
}

// Len reports the number of queued items.
func (q *Queue) Len() int {
	return len(q.items)
}

// Drain transfers the backing slice to the caller and leaves q empty. After
// this call the returned slice is the caller's mutable data, not queue state.
func (q *Queue) Drain() []string {
	items := q.items
	q.items = nil
	return items
}

// Package middleware demonstrates function-based handler composition.
package middleware

import "maps"

// Request is the input passed through a handler chain.
type Request struct {
	Path string
}

// Response is the value returned by a handler chain.
type Response struct {
	Status  int
	Body    string
	Headers map[string]string
}

// Handler handles a request.
type Handler func(Request) Response

// Middleware wraps a Handler with cross-cutting behavior.
type Middleware func(Handler) Handler

// Chain applies middleware so the first item is the outermost wrapper.
func Chain(endpoint Handler, middleware ...Middleware) Handler {
	for i := len(middleware) - 1; i >= 0; i-- {
		if middleware[i] != nil {
			endpoint = middleware[i](endpoint)
		}
	}
	return endpoint
}

// PrefixBody adds a deterministic prefix to a successful or failed response.
func PrefixBody(prefix string) Middleware {
	return func(next Handler) Handler {
		return func(request Request) Response {
			response := next(request)
			response.Body = prefix + ":" + response.Body
			return response
		}
	}
}

// AddHeader adds or replaces one response header while preserving headers set
// by the endpoint and inner middleware.
func AddHeader(name, value string) Middleware {
	return func(next Handler) Handler {
		return func(request Request) Response {
			response := next(request)
			response.Headers = maps.Clone(response.Headers)
			if response.Headers == nil {
				response.Headers = make(map[string]string)
			}
			response.Headers[name] = value
			return response
		}
	}
}

// Package sharedmap demonstrates protecting a map behind a mutex and returning
// snapshots instead of exposing shared mutable state.
package sharedmap

import "sync"

// Store is safe for concurrent use. Do not copy a Store after first use.
type Store struct {
	mu     sync.RWMutex
	values map[string]int
}

// NewStore creates an initialized Store.
func NewStore() *Store {
	return &Store{values: make(map[string]int)}
}

// Set associates value with key.
func (s *Store) Set(key string, value int) {
	s.mu.Lock()
	defer s.mu.Unlock()
	if s.values == nil {
		s.values = make(map[string]int)
	}
	s.values[key] = value
}

// Get returns the value for key, if present.
func (s *Store) Get(key string) (int, bool) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	value, ok := s.values[key]
	return value, ok
}

// Len returns the number of stored keys.
func (s *Store) Len() int {
	s.mu.RLock()
	defer s.mu.RUnlock()
	return len(s.values)
}

// Snapshot returns a copy that the caller may mutate independently.
func (s *Store) Snapshot() map[string]int {
	s.mu.RLock()
	defer s.mu.RUnlock()

	snapshot := make(map[string]int, len(s.values))
	for key, value := range s.values {
		snapshot[key] = value
	}
	return snapshot
}

// Package sliceboundary demonstrates defensive copying at slice boundaries.
package sliceboundary

import "slices"

// Batch owns its items. The backing array is never exposed directly.
type Batch struct {
	items []string
}

// NewBatch copies items so later caller mutations cannot change the Batch.
func NewBatch(items []string) Batch {
	return Batch{items: slices.Clone(items)}
}

// Len reports the number of items.
func (b Batch) Len() int {
	return len(b.items)
}

// Items returns a copy so caller mutations cannot change the Batch.
func (b Batch) Items() []string {
	return slices.Clone(b.items)
}

// Package cancellation demonstrates context cancellation in a channel loop.
package cancellation

import "context"

// Process consumes jobs until the channel closes or ctx is canceled. Results
// completed before cancellation are returned together with ctx.Err(). The
// callback runs synchronously, so there is no worker goroutine to leak.
func Process(ctx context.Context, jobs <-chan int, fn func(int) int) ([]int, error) {
	var results []int
	for {
		// Checking before select makes an already-canceled context deterministic
		// even when jobs is also ready.
		if err := ctx.Err(); err != nil {
			return results, err
		}

		select {
		case <-ctx.Done():
			return results, ctx.Err()
		case job, ok := <-jobs:
			if !ok {
				return results, nil
			}
			// The callback may cancel ctx. Do not start another job after that.
			if err := ctx.Err(); err != nil {
				return results, err
			}
			results = append(results, fn(job))
		}
	}
}