Итоговый проект: REST API на Gin

// internal/todo/domain.go — домен и сентинелы
type Todo struct {
        ID        int64
        OwnerID   int64
        Title     string
        CreatedAt time.Time
}

type TodoInput struct {
        Title string `json:"title" binding:"required,min=1,max=140"`
}

var (
        ErrNotFound = errors.New("todo: задача не найдена")          // → 404 NOT_FOUND
        ErrConflict = errors.New("todo: дубликат заголовка")          // → 409 CONFLICT
        ErrBadID    = errors.New("todo: id должен быть числом")       // → 400 BAD_REQUEST
)

// internal/todo/store.go — контракт данных, объявлен у потребителя
type Store interface {
        Get(ctx context.Context, id, ownerID int64) (Todo, error)
        List(ctx context.Context, ownerID int64) ([]Todo, error)
        Create(ctx context.Context, t Todo) (Todo, error)
        Update(ctx context.Context, t Todo) (Todo, error)
        Delete(ctx context.Context, id, ownerID int64) error
}

// internal/todo/memory.go — реализация для тестов и локального пуска
type MemoryStore struct {
        mu   sync.RWMutex
        next int64
        byID map[int64]Todo
}

func NewMemoryStore() *MemoryStore { return &MemoryStore{byID: map[int64]Todo{}} }

func (s *MemoryStore) Create(_ context.Context, t Todo) (Todo, error) {
        s.mu.Lock()
        defer s.mu.Unlock()
        s.next++
        t.ID, t.CreatedAt = s.next, time.Now()
        s.byID[t.ID] = t
        return t, nil
}

func (s *MemoryStore) Get(_ context.Context, id, ownerID int64) (Todo, error) {
        s.mu.RLock()
        defer s.mu.RUnlock()
        t, ok := s.byID[id]
        if !ok || t.OwnerID != ownerID {
                return Todo{}, ErrNotFound // чужая задача = несуществующая
        }
        return t, nil
}

// List, Update и Delete — по той же схеме: RLock на чтение, Lock на запись,
// фильтр по ownerID, ErrNotFound при промахе; List возвращает непустой срез.

// internal/todo/service.go
type Service struct {
        st Store
}

func NewService(st Store) *Service { return &Service{st: st} }

func (s *Service) Create(ctx context.Context, ownerID int64, in TodoInput) (Todo, error) {
        todos, err := s.st.List(ctx, ownerID)
        if err != nil {
                return Todo{}, fmt.Errorf("list для дубликатов: %w", err)
        }
        for _, t := range todos { // дубликат — доменное правило, не транспорт
                if strings.EqualFold(t.Title, in.Title) {
                        return Todo{}, ErrConflict
                }
        }
        return s.st.Create(ctx, Todo{OwnerID: ownerID, Title: in.Title})
}

func (s *Service) Update(ctx context.Context, ownerID, id int64, in TodoInput) (Todo, error) {
        t, err := s.st.Get(ctx, id, ownerID)
        if err != nil {
                return Todo{}, fmt.Errorf("get %d: %w", id, err)
        }
        t.Title = in.Title
        if _, err := s.st.Update(ctx, t); err != nil {
                return Todo{}, fmt.Errorf("update %d: %w", id, err)
        }
        return t, nil
}

func (s *Service) Get(ctx context.Context, ownerID, id int64) (Todo, error) {
        t, err := s.st.Get(ctx, id, ownerID)
        if err != nil {
                return Todo{}, fmt.Errorf("get %d: %w", id, err)
        }
        return t, nil
}

func (s *Service) Delete(ctx context.Context, ownerID, id int64) error {
        return s.st.Delete(ctx, id, ownerID)
}

// internal/todo/handler.go
type Handler struct {
        svc *Service
}

func NewHandler(svc *Service) *Handler { return &Handler{svc: svc} }

// RegisterRoutes вешает маршруты на группу; группа уже под Auth().
func (h *Handler) RegisterRoutes(v1 *gin.RouterGroup) {
        todos := v1.Group("/todos")
        todos.POST("", h.create)
        todos.GET("", h.list)
        todos.GET("/:id", h.get)
        todos.PATCH("/:id", h.update)
        todos.DELETE("/:id", h.remove)
}

func (h *Handler) create(c *gin.Context) {
        var in TodoInput
        if err := c.ShouldBindJSON(&in); err != nil {
                handleError(c, err) // 400 VALIDATION_FAILED с details
                return
        }
        claims := c.MustGet("claims").(*UserClaims)
        t, err := h.svc.Create(c.Request.Context(), claims.UserID, in)
        if err != nil {
                handleError(c, err) // 409 CONFLICT на дубликат
                return
        }
        respondData(c, http.StatusCreated, t)
}

func (h *Handler) get(c *gin.Context) {
        id, err := strconv.ParseInt(c.Param("id"), 10, 64)
        if err != nil {
                handleError(c, fmt.Errorf("%w: %s", ErrBadID, c.Param("id")))
                return
        }
        claims := c.MustGet("claims").(*UserClaims)
        t, err := h.svc.Get(c.Request.Context(), claims.UserID, id)
        if err != nil {
                handleError(c, err) // 404 NOT_FOUND, даже если задача чужая
                return
        }
        respondData(c, http.StatusOK, t)
}

// list, update и remove — по той же схеме:
// remove отвечает c.Status(http.StatusNoContent) без тела.

// cmd/server/main.go — единственное место, где всё знают друг о друге
func main() {
        cfg, err := config.Load() // PORT, DSN, JWT_SECRET: падаем на пустом
        if err != nil {
                log.Fatalf("config: %v", err)
        }
        gin.SetMode(cfg.Mode) // release в проде из урока 24

        pool, err := pgxpool.New(context.Background(), cfg.DSN)
        if err != nil {
                log.Fatalf("pgxpool: %v", err)
        }

        repo := todo.NewPostgresStore(pool) // прод-реализация Store
        svc := todo.NewService(repo)
        h := todo.NewHandler(svc)

        engine := gin.New()
        engine.Use(
            middleware.Logger(slog.Default()),
            middleware.Recovery(slog.Default()),
            middleware.CORS(),
            middleware.PerIPLimit(cfg.RPS, cfg.Burst), // 18-й урок
        )
        v1 := engine.Group("/api/v1")
        v1.Use(middleware.Auth()) // гвард 15-го урока на всю группу
        h.RegisterRoutes(v1)

        engine.GET("/healthz", healthz(version))
        engine.GET("/readyz", readyz(pool))
        log.Fatal(run(engine, cfg, pool)) // сервер и graceful — дальше
}

v1 := engine.Group("/api/v1")
v1.Use(middleware.Auth())
h.RegisterRoutes(v1)

// клиент отправляет:
// POST /api/v1/todos
// {"title":"собрать выпускной проект"}
// Заголовок Authorization отсутствует

// internal/middleware/limit.go
type ipLimiter struct {
        mu       sync.Mutex
        visitors map[string]*rate.Limiter
        rps      rate.Limit
        burst    int
}

func PerIPLimit(rps rate.Limit, burst int) gin.HandlerFunc {
        l := &ipLimiter{visitors: map[string]*rate.Limiter{}, rps: rps, burst: burst}
        go l.cleaner(time.Minute) // выкидываем молчащих гостей
        return func(c *gin.Context) {
                lim := l.get(c.ClientIP())
                res := lim.Reserve() // бронируем токен, чтобы знать Delay
                if res == nil {
                        tooMany(c, time.Second)
                        return
                }
                if d := res.Delay(); d > 0 {
                        res.Cancel() // бронь возвращаем — не ждём
                        tooMany(c, d)
                        return
                }
                c.Next()
        }
}

func (l *ipLimiter) get(ip string) *rate.Limiter {
        l.mu.Lock()
        defer l.mu.Unlock()
        lim, ok := l.visitors[ip]
        if !ok {
                lim = rate.NewLimiter(l.rps, l.burst)
                l.visitors[ip] = lim
        }
        return lim
}

func tooMany(c *gin.Context, wait time.Duration) {
        c.Header("Retry-After", strconv.Itoa(int(math.Ceil(wait.Seconds()))))
        respondError(c, http.StatusTooManyRequests, "RATE_LIMITED", "слишком много запросов")
        c.Abort()
}

// cmd/server/main.go — продолжение
func run(engine *gin.Engine, cfg config.Config, pool *pgxpool.Pool) error {
        srv := &http.Server{
                Addr:              cfg.Addr,
                Handler:           engine,
                ReadHeaderTimeout: 5 * time.Second,
                ReadTimeout:       15 * time.Second,
                WriteTimeout:      30 * time.Second,
                IdleTimeout:       120 * time.Second,
        }
        ctx, stop := signal.NotifyContext(context.Background(),
                os.Interrupt, syscall.SIGTERM)
        defer stop()

        errCh := make(chan error, 1)
        go func() {
                if err := srv.ListenAndServe(); err != nil &&
                        !errors.Is(err, http.ErrServerClosed) {
                        errCh <- err
                }
        }()

        select {
        case err := <-errCh: // порт занят и прочие ошибки старта
                return err
        case <-ctx.Done(): // SIGTERM: начинаем дренаж
        }
        stop() // следующий сигнал рубит жёстко — это фича

        drainCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
        defer cancel()
        if err := srv.Shutdown(drainCtx); err != nil {
                return fmt.Errorf("shutdown: %w", err)
        }
        return pool.Close() // базу закрываем последней
}

// internal/todo/handler_test.go
func setupRouter(st Store) *gin.Engine {
        gin.SetMode(gin.TestMode)
        engine := gin.New()
        v1 := engine.Group("/api/v1")
        v1.Use(func(c *gin.Context) { // гвард уже проверен в своих тестах
                c.Set("claims", &UserClaims{UserID: 42})
                c.Next()
        })
        NewHandler(NewService(st)).RegisterRoutes(v1)
        return engine
}

func TestTodosAPI(t *testing.T) {
        tests := []struct {
                name, method, path, body string
                st                       Store
                want                     int
                wantErr                  string
        }{
                {"создание", "POST", "/api/v1/todos", `{"title":"выучить gin"}`,
                        NewMemoryStore(), http.StatusCreated, ""},
                {"дубликат", "POST", "/api/v1/todos", `{"title":"выучить gin"}`,
                        stubStore{list: []Todo{{ID: 1, OwnerID: 42, Title: "выучить gin"}}},
                        http.StatusConflict, "CONFLICT"},
                {"промах", "GET", "/api/v1/todos/7", "",
                        stubStore{err: ErrNotFound}, http.StatusNotFound, "NOT_FOUND"},
                {"битый id", "GET", "/api/v1/todos/abc", "",
                        NewMemoryStore(), http.StatusBadRequest, "BAD_REQUEST"},
        }
        for _, tt := range tests {
                t.Run(tt.name, func(t *testing.T) {
                        router := setupRouter(tt.st) // свежий стор на кейс
                        w := httptest.NewRecorder()
                        req := httptest.NewRequest(tt.method, tt.path,
                                strings.NewReader(tt.body))
                        req.Header.Set("Content-Type", "application/json")
                        router.ServeHTTP(w, req)
                        if w.Code != tt.want {
                                t.Fatalf("code=%d want=%d body=%s", w.Code, tt.want, w.Body)
                        }
                        if tt.wantErr != "" &&
                                !strings.Contains(w.Body.String(), tt.wantErr) {
                                t.Fatalf("нет кода %s в %s", tt.wantErr, w.Body)
                        }
                })
        }
}

// stubStore{err: ErrNotFound} подставлен в setupRouter:
// Get и List возвращают заготовленную ошибку

// тест шлёт:
// GET /api/v1/todos/7
// Authorization: Bearer <валидный токен>