ハンズオン: サービスを1本作って動かす

cd examples/hands-on
make test
make run

curl -s -X POST localhost:8080/v1/links \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://go.dev/doc/effective_go"}'

{"key":"oyezGIN","url":"https://go.dev/doc/effective_go","created_at":"2026-08-05T07:31:22.056344Z"}

syntax = "proto3";
 
package link.v1;
 
import "google/protobuf/timestamp.proto";
 
option go_package = "github.com/example/linkshort/gen/link/v1;linkv1";
 
service LinkService {
  rpc CreateLink(CreateLinkRequest) returns (CreateLinkResponse);
  rpc GetLink(GetLinkRequest) returns (GetLinkResponse);
  rpc ListLinks(ListLinksRequest) returns (ListLinksResponse);
}
 
message Link {
  string key = 1;
  string url = 2;
  google.protobuf.Timestamp create_time = 3;
}
 
message CreateLinkRequest {
  string url = 1;
}
 
message CreateLinkResponse {
  Link link = 1;
}
 
message ListLinksRequest {
  // 0 ならサーバー既定値(20)。上限は 100。
  int32 page_size = 1;
  // 前回の応答の next_page_token をそのまま渡す。中身は不透明。
  string page_token = 2;
}
 
message ListLinksResponse {
  repeated Link links = 1;
  // 空文字なら最終ページ。
  string next_page_token = 2;
}

gen:
	mkdir -p gen
	protoc -I proto \
		--go_out=gen --go_opt=paths=source_relative \
		--go-grpc_out=gen --go-grpc_opt=paths=source_relative \
		proto/link/v1/link.proto

mkdir -p linkshort && cd linkshort
go mod init github.com/example/linkshort
mkdir -p cmd/server internal/service internal/store proto/link/v1 k8s

services:
  linkshort:
    build: .
    image: linkshort:dev
    ports:
      - "8080:8080"
    environment:
      ADDR: ":8080"
    restart: unless-stopped

package store
 
var (
	ErrNotFound = errors.New("store: link not found")
	ErrConflict = errors.New("store: key already exists")
)
 
type Link struct {
	Key       string
	URL       string
	CreatedAt time.Time
}
 
// Store は保存先の口。呼び出し側はこの口だけに依存するので、
// インメモリを PostgreSQL に差し替えても service は変わらない。
type Store interface {
	Create(ctx context.Context, link Link) error
	Get(ctx context.Context, key string) (Link, error)
	// List は after より後ろのキーを昇順で最大 limit 件返す。
	List(ctx context.Context, limit int, after string) ([]Link, error)
}

type Memory struct {
	mu    sync.RWMutex
	links map[string]Link
}
 
func NewMemory() *Memory {
	return &Memory{links: make(map[string]Link)}
}
 
func (m *Memory) Create(_ context.Context, link Link) error {
	m.mu.Lock()
	defer m.mu.Unlock()
 
	if _, exists := m.links[link.Key]; exists {
		return ErrConflict
	}
	m.links[link.Key] = link
	return nil
}

func (m *Memory) List(_ context.Context, limit int, after string) ([]Link, error) {
	m.mu.RLock()
	defer m.mu.RUnlock()
 
	// キーの全順序で区切ることで、途中で件数が増減してもページ境界がずれない
	keys := make([]string, 0, len(m.links))
	for key := range m.links {
		if key > after {
			keys = append(keys, key)
		}
	}
	sort.Strings(keys)
	if len(keys) > limit {
		keys = keys[:limit]
	}
 
	links := make([]Link, 0, len(keys))
	for _, key := range keys {
		links = append(links, m.links[key])
	}
	return links, nil
}

type Config struct {
	Store  store.Store
	NewKey func() (string, error)
	Now    func() time.Time
	Logger *slog.Logger
}
 
type Service struct {
	store  store.Store
	newKey func() (string, error)
	now    func() time.Time
	logger *slog.Logger
}
 
func New(cfg Config) *Service {
	svc := &Service{store: cfg.Store, newKey: cfg.NewKey, now: cfg.Now, logger: cfg.Logger}
	if svc.newKey == nil {
		svc.newKey = RandomKey
	}
	if svc.now == nil {
		svc.now = time.Now
	}
	if svc.logger == nil {
		svc.logger = slog.Default()
	}
	return svc
}

func (s *Service) CreateLink(ctx context.Context, rawURL string) (Link, error) {
	target, err := normalizeURL(rawURL)
	if err != nil {
		return Link{}, err
	}
 
	created, err := s.storeWithNewKey(ctx, target)
	if err != nil {
		return Link{}, err
	}
 
	s.logger.InfoContext(ctx, "link created", "key", created.Key, "url", created.URL)
	return toLink(created), nil
}
 
// storeWithNewKey はキー衝突のときだけ採番からやり直す。
func (s *Service) storeWithNewKey(ctx context.Context, target string) (store.Link, error) {
	for attempt := range createMaxRetry {
		key, err := s.newKey()
		if err != nil {
			return store.Link{}, fmt.Errorf("generate key: %w", err)
		}
 
		record := store.Link{Key: key, URL: target, CreatedAt: s.now().UTC()}
		switch err := s.store.Create(ctx, record); {
		case err == nil:
			return record, nil
		case errors.Is(err, store.ErrConflict):
			s.logger.WarnContext(ctx, "key collision", "key", key, "attempt", attempt+1)
		default:
			return store.Link{}, fmt.Errorf("create link: %w", err)
		}
	}
	return store.Link{}, ErrExhausted
}

func normalizeURL(rawURL string) (string, error) {
	trimmed := strings.TrimSpace(rawURL)
	if trimmed == "" {
		return "", fmt.Errorf("%w: url is required", ErrInvalidArgument)
	}
	if len(trimmed) > maxURLLength {
		return "", fmt.Errorf("%w: url is too long", ErrInvalidArgument)
	}
 
	parsed, err := url.Parse(trimmed)
	if err != nil {
		return "", fmt.Errorf("%w: url is not parsable", ErrInvalidArgument)
	}
	// javascript: や file: を通すと、転送先がそのまま攻撃面になる
	if parsed.Scheme != "http" && parsed.Scheme != "https" {
		return "", fmt.Errorf("%w: url must be http or https", ErrInvalidArgument)
	}
	if parsed.Host == "" {
		return "", fmt.Errorf("%w: url must have a host", ErrInvalidArgument)
	}
	return parsed.String(), nil
}

const keyAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
 
func RandomKey() (string, error) {
	limit := big.NewInt(int64(len(keyAlphabet)))
	key := make([]byte, keyLength)
	for i := range key {
		n, err := rand.Int(rand.Reader, limit)
		if err != nil {
			return "", err
		}
		key[i] = keyAlphabet[n.Int64()]
	}
	return string(key), nil
}

func (s *Service) ListLinks(ctx context.Context, req ListLinksRequest) (ListLinksResponse, error) {
	size, err := normalizePageSize(req.PageSize)
	if err != nil {
		return ListLinksResponse{}, err
	}
	after, err := decodePageToken(req.PageToken)
	if err != nil {
		return ListLinksResponse{}, err
	}
 
	// 次ページの有無を知るために1件多く取る
	records, err := s.store.List(ctx, size+1, after)
	if err != nil {
		return ListLinksResponse{}, fmt.Errorf("list links: %w", err)
	}
 
	next := ""
	if len(records) > size {
		next = encodePageToken(records[size-1].Key)
		records = records[:size]
	}
	...
}

func encodePageToken(key string) string {
	return base64.RawURLEncoding.EncodeToString([]byte(key))
}

func normalizePageSize(size int) (int, error) {
	switch {
	case size < 0:
		return 0, fmt.Errorf("%w: page_size must not be negative", ErrInvalidArgument)
	case size == 0:
		return defaultPageSize, nil
	case size > maxPageSize:
		return maxPageSize, nil
	default:
		return size, nil
	}
}

var fixedTime = time.Date(2026, 4, 1, 9, 0, 0, 0, time.UTC)
 
func newTestService(t *testing.T) (*service.Service, store.Store) {
	t.Helper()
 
	memory := store.NewMemory()
	counter := 0
	svc := service.New(service.Config{
		Store: memory,
		NewKey: func() (string, error) {
			counter++
			return fmt.Sprintf("key%03d", counter), nil
		},
		Now:    func() time.Time { return fixedTime },
		Logger: slog.New(slog.NewTextHandler(io.Discard, nil)),
	})
	return svc, memory
}

func TestCreateLink(t *testing.T) {
	tests := []struct {
		name    string
		url     string
		wantURL string
		wantErr error
	}{
		{name: "https を受け付ける", url: "https://example.com/a", wantURL: "https://example.com/a"},
		{name: "前後の空白を落とす", url: "  https://example.com/b  ", wantURL: "https://example.com/b"},
		{name: "空文字は弾く", url: "", wantErr: service.ErrInvalidArgument},
		{name: "スキームなしは弾く", url: "example.com", wantErr: service.ErrInvalidArgument},
		{name: "javascript は弾く", url: "javascript:alert(1)", wantErr: service.ErrInvalidArgument},
		{name: "ホストなしは弾く", url: "https://", wantErr: service.ErrInvalidArgument},
	}
 
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			svc, _ := newTestService(t)
 
			got, err := svc.CreateLink(context.Background(), tt.url)
 
			if !errors.Is(err, tt.wantErr) {
				t.Fatalf("err = %v, want %v", err, tt.wantErr)
			}
			if tt.wantErr != nil {
				return
			}
			if got.URL != tt.wantURL {
				t.Errorf("URL = %q, want %q", got.URL, tt.wantURL)
			}
		})
	}
}

// failingStore は「保存先が落ちた」状況を作るための差し替え実装。
type failingStore struct {
	store.Store
	err error
}
 
func (f failingStore) Create(context.Context, store.Link) error { return f.err }
 
func TestCreateLinkPropagatesStoreFailure(t *testing.T) {
	boom := errors.New("disk on fire")
	svc := service.New(service.Config{
		Store:  failingStore{Store: store.NewMemory(), err: boom},
		NewKey: func() (string, error) { return "fixedkey", nil },
		Logger: slog.New(slog.NewTextHandler(io.Discard, nil)),
	})
 
	_, err := svc.CreateLink(context.Background(), "https://example.com")
 
	if !errors.Is(err, boom) {
		t.Fatalf("err = %v, want %v をラップした値", err, boom)
	}
}

func TestListLinksWalksEveryPageOnce(t *testing.T) {
	svc, _ := newTestService(t)
	const total = 23
	seedLinks(t, svc, total)
 
	seen := make(map[string]int)
	token := ""
	for page := 0; ; page++ {
		if page > total {
			t.Fatal("ページ送りが終わりません")
		}
		got, err := svc.ListLinks(context.Background(), service.ListLinksRequest{PageSize: 5, PageToken: token})
		if err != nil {
			t.Fatalf("ListLinks: %v", err)
		}
		for _, link := range got.Links {
			seen[link.Key]++
		}
		if got.NextPageToken == "" {
			break
		}
		token = got.NextPageToken
	}
 
	if len(seen) != total {
		t.Errorf("見えた件数 = %d, want %d", len(seen), total)
	}
}

go test ./...
go test -race ./...   # 同時アクセスのバグを見つける

func newRouter(svc *service.Service) http.Handler {
	handlers := &api{svc: svc}
	mux := http.NewServeMux()
 
	mux.HandleFunc("POST /v1/links", handlers.createLink)
	mux.HandleFunc("GET /v1/links", handlers.listLinks)
	mux.HandleFunc("GET /v1/links/{key}", handlers.getLink)
	mux.HandleFunc("GET /r/{key}", handlers.redirect)
	mux.HandleFunc("GET /healthz", alwaysOK)
	mux.HandleFunc("GET /readyz", alwaysOK)
 
	return mux
}

func (a *api) createLink(w http.ResponseWriter, r *http.Request) {
	var body struct {
		URL string `json:"url"`
	}
	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&body); err != nil {
		writeError(w, r, http.StatusBadRequest, "リクエストボディが JSON として読めません")
		return
	}
 
	link, err := a.svc.CreateLink(r.Context(), body.URL)
	if err != nil {
		writeServiceError(w, r, err)
		return
	}
	writeJSON(w, http.StatusCreated, link)
}

func writeServiceError(w http.ResponseWriter, r *http.Request, err error) {
	switch {
	case errors.Is(err, service.ErrInvalidArgument):
		writeError(w, r, http.StatusBadRequest, err.Error())
	case errors.Is(err, service.ErrNotFound):
		writeError(w, r, http.StatusNotFound, "そのキーのリンクはありません")
	default:
		slog.ErrorContext(r.Context(), "unhandled error", "error", err, "path", r.URL.Path)
		writeError(w, r, http.StatusInternalServerError, "内部エラーが発生しました")
	}
}

func withRequestLog(next http.Handler, logger *slog.Logger) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		started := time.Now()
		recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
 
		next.ServeHTTP(recorder, r)
 
		logger.InfoContext(r.Context(), "http request",
			"method", r.Method,
			"path", r.URL.Path,
			"status", recorder.status,
			"duration_ms", time.Since(started).Milliseconds(),
			"user_agent", r.UserAgent(),
		)
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}
 
func (s *statusRecorder) WriteHeader(status int) {
	s.status = status
	s.ResponseWriter.WriteHeader(status)
}

func run(server *http.Server, logger *slog.Logger) error {
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()
 
	errCh := make(chan error, 1)
	go func() {
		logger.Info("server listening", "addr", server.Addr)
		errCh <- server.ListenAndServe()
	}()
 
	select {
	case err := <-errCh:
		if errors.Is(err, http.ErrServerClosed) {
			return nil
		}
		return err
	case <-ctx.Done():
		logger.Info("shutdown signal received")
		shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
		defer cancel()
		return server.Shutdown(shutdownCtx)
	}
}

go run ./cmd/server

{"time":"2026-08-05T16:31:19.114815+09:00","level":"INFO","msg":"server listening","addr":":8080"}

# 作る
curl -s -X POST localhost:8080/v1/links \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://go.dev/doc/effective_go"}'

{"key":"oyezGIN","url":"https://go.dev/doc/effective_go","created_at":"2026-08-05T07:31:22.056344Z"}

# 引く
curl -s localhost:8080/v1/links/oyezGIN
 
# 弾かれることを確かめる
curl -s -w ' status=%{http_code}\n' -X POST localhost:8080/v1/links \
  -d '{"url":"javascript:alert(1)"}'

{"error":"invalid argument: url must be http or https"} status=400

# 一覧をページ送りする
curl -s 'localhost:8080/v1/links?page_size=2'

{"links":[{"key":"BktH3sQ","url":"https://example.com/2","created_at":"..."},
{"key":"b6nlkBE","url":"https://example.com/3","created_at":"..."}],
"next_page_token":"YjZubGtCRQ"}

curl -s 'localhost:8080/v1/links?page_size=2&page_token=YjZubGtCRQ'

curl -s -i localhost:8080/r/oyezGIN | head -3

{"time":"...","level":"INFO","msg":"link created","key":"oyezGIN","url":"https://go.dev/doc/effective_go"}
{"time":"...","level":"INFO","msg":"http request","method":"POST","path":"/v1/links","status":201,"duration_ms":0,"user_agent":"curl/8.7.1"}
{"time":"...","level":"WARN","msg":"request rejected","status":400,"message":"invalid argument: url must be http or https"}

go run ./cmd/server 2>&1 | jq 'select(.status >= 400)'

# --- 1段目: ビルドだけを行う。Go ツールチェインは成果物に持ち込まない ---
FROM golang:1.24-alpine AS build
 
WORKDIR /src
 
# 依存の解決だけを先に済ませると、コードを直してもこの層のキャッシュが効く
COPY go.mod ./
RUN go mod download
 
COPY . .
 
# CGO を切って静的リンクにする。これで libc の無いイメージでも動く
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/server ./cmd/server
 
# --- 2段目: バイナリ1つだけの最小イメージ。シェルもパッケージマネージャも無い ---
FROM gcr.io/distroless/static-debian12:nonroot
 
COPY --from=build /out/server /server
 
# root で動かさない。コンテナを破られても、できることを減らしておく
USER nonroot:nonroot
 
EXPOSE 8080
 
ENTRYPOINT ["/server"]

docker build -t linkshort:dev .
docker compose up --build -d
curl -s localhost:8080/healthz

apiVersion: apps/v1
kind: Deployment
metadata:
  name: linkshort
spec:
  replicas: 2
  selector:
    matchLabels:
      app: linkshort
  template:
    metadata:
      labels:
        app: linkshort
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
      containers:
        - name: server
          image: linkshort:dev
          ports:
            - name: http
              containerPort: 8080
          # 落ちていたら再起動する。重い依存を見に行かせないこと
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
            initialDelaySeconds: 3
            periodSeconds: 10
            failureThreshold: 3
          # 受け入れ準備ができたらトラフィックを流す。失敗しても再起動はしない
          readinessProbe:
            httpGet:
              path: /readyz
              port: http
            initialDelaySeconds: 1
            periodSeconds: 5
            failureThreshold: 3
          resources:
            # requests はスケジューラが置き場所を決める基準、limits は上限
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 500m
              memory: 128Mi
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]
      # SIGTERM 後にロードバランサから外れる猶予を取る
      terminationGracePeriodSeconds: 30

apiVersion: v1
kind: Service
metadata:
  name: linkshort
spec:
  type: ClusterIP
  selector:
    app: linkshort
  ports:
    - name: http
      port: 80
      targetPort: http

kubectl apply -f k8s/
kubectl get pods -l app=linkshort
kubectl logs -l app=linkshort -f
kubectl port-forward svc/linkshort 8080:80

name: ci
 
on:
  push:
    branches: [main]
  pull_request:
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'
          cache: true
 
      - name: format
        run: test -z "$(gofmt -l .)"
 
      - name: vet
        run: go vet ./...
 
      - name: test
        run: go test -race ./...
 
      - name: build image
        run: docker build -t linkshort:${{ github.sha }} .

type Postgres struct {
	db *sql.DB
}
 
func (p *Postgres) Create(ctx context.Context, link store.Link) error {
	// 文字列結合は絶対にしない。プレースホルダを使う
	_, err := p.db.ExecContext(ctx,
		`INSERT INTO links (key, url, created_at) VALUES ($1, $2, $3)`,
		link.Key, link.URL, link.CreatedAt)
	return err
}

type grpcServer struct {
	linkv1.UnimplementedLinkServiceServer
	svc *service.Service
}
 
func (g *grpcServer) CreateLink(ctx context.Context, req *linkv1.CreateLinkRequest) (*linkv1.CreateLinkResponse, error) {
	link, err := g.svc.CreateLink(ctx, req.GetUrl())
	if err != nil {
		return nil, toStatusError(err)  // ErrInvalidArgument → codes.InvalidArgument
	}
	return &linkv1.CreateLinkResponse{Link: toProto(link)}, nil
}