Spine

https://spine.na2ru2.me/ko
Admin
Spine is a Go framework that provides an explicit execution pipeline for requests, revealing how...
Tokens:83,353
Snippets:737
Trust Score:2.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Full Spine Application Implementation

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

A complete example demonstrating constructor registration, HTTP routing, global interceptors, event consumers, and WebSocket setup.

```go
package main

import (
    "context"
    "encoding/json"
    "log"
    "strings"
    "sync"
    "time"

    "github.com/NARUBROWN/spine"
    "github.com/NARUBROWN/spine/interceptor/cors"
    "github.com/NARUBROWN/spine/pkg/boot"
    "github.com/NARUBROWN/spine/pkg/event/publish"
    "github.com/NARUBROWN/spine/pkg/httpx"
    "github.com/NARUBROWN/spine/pkg/path"
    "github.com/NARUBROWN/spine/pkg/route"
    "github.com/NARUBROWN/spine/pkg/ws"
)

func main() {
    app := spine.New()

    // 생성자 등록
    app.Constructor(
        NewUserController,
        NewOrderConsumer,
        NewChatController,
    )

    // HTTP 라우트 등록
    app.Route("GET", "/users", (*UserController).GetUserQuery)
    app.Route("GET", "/users/:id", (*UserController).GetUser,
        route.WithInterceptors(&LoggingInterceptor{}),
    )
    app.Route("POST", "/orders/:orderId", (*UserController).CreateOrder)

    // 전역 Interceptor 등록
    app.Interceptor(
        cors.New(cors.Config{
            AllowOrigins: []string{"*"},
            AllowMethods: []string{"GET", "POST", "OPTIONS"},
            AllowHeaders: []string{"Content-Type"},
        }),
    )

    // 이벤트 컨슈머 등록
    if err := app.Consumers().Register("order.created", (*OrderConsumer).OnCreated); err != nil {
        log.Fatal(err)
    }

    // WebSocket 등록
    if err := app.WebSocket().Register("/ws/chat", (*ChatController).OnMessage); err != nil {
        log.Fatal(err)
    }

    // 서버 실행
    if err := app.Run(boot.Options{
        Address:                ":8080",
        EnableGracefulShutdown: true,
        ShutdownTimeout:        10 * time.Second,
        RabbitMQ: &boot.RabbitMqOptions{
            URL: "amqp://guest:guest@localhost:5672/",
            Read: &boot.RabbitMqReadOptions{
                Exchange: "stock-exchange",
            },
            Write: &boot.RabbitMqWriteOptions{
                Exchange: "stock-exchange",
            },
        },
        HTTP: &boot.HTTPOptions{},
    }); err != nil {
        log.Fatal(err)
    }
}

// Controller
type UserController struct{}

func NewUserController() *UserController {
    return &UserController{}
}

func (c *UserController) CreateOrder(ctx context.Context, orderId path.Int) httpx.Response[string] {
    publish.Event(ctx, OrderCreated{
        OrderID: orderId.Value,
        At:      time.Now(),
    })
    return httpx.Response[string]{Body: "OK"}
}

// Event
type OrderCreated struct {
    OrderID int64     `json:"order_id"`
    At      time.Time `json:"at"`
}

func (e OrderCreated) Name() string        { return "order.created" }
func (e OrderCreated) OccurredAt() time.Time { return e.At }

// Consumer
type OrderConsumer struct{}

func NewOrderConsumer() *OrderConsumer {
    return &OrderConsumer{}
}

func (c *OrderConsumer) OnCreated(
    ctx context.Context,
    eventName string,
    event OrderCreated,
) error {
    log.Println("이벤트 수신:", eventName)
    log.Println("주문 ID:", event.OrderID)
    return nil
}

// WebSocket
type ChatController struct {
    mu      sync.RWMutex
    clients map[string]ws.Sender
}

func NewChatController() *ChatController {
    return &ChatController{clients: make(map[string]ws.Sender)}
}

type ChatMessage struct {
    Message string `json:"message"`
}

type ChatEvent struct {
    Type    string `json:"type"`
    From    string `json:"from"`
    Message string `json:"message"`
    At      string `json:"at"`
}

func (c *ChatController) OnMessage(
    ctx context.Context,
    connID ws.ConnectionID,
    msg ChatMessage,
) error {
    sender, ok := ctx.Value(ws.SenderKey).(ws.Sender)
    if ok && sender != nil {
        c.mu.Lock()
        c.clients[connID.Value] = sender
        c.mu.Unlock()
    }

    message := strings.TrimSpace(msg.Message)
    if message == "" {
        return nil
    }

    payload, err := json.Marshal(ChatEvent{
        Type:    "message",
        From:    connID.Value,
        Message: message,
        At:      time.Now().UTC().Format(time.RFC3339),
    })
    if err != nil {
        return err
    }

    c.mu.RLock()
    clients := make(map[string]ws.Sender, len(c.clients))
    for id, client := range c.clients {
        clients[id] = client
    }
    c.mu.RUnlock()

    var firstErr error
    for id, client := range clients {
        if err := client.Send(ws.TextMessage, payload); err != nil {
            if firstErr == nil {
                firstErr = err
            }
            c.mu.Lock()
            delete(c.clients, id)
            c.mu.Unlock()
        }
    }
    return firstErr
}
```

--------------------------------

### Basic application run

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Minimal configuration to start the application.

```go
app.Run(boot.Options{
    Address: ":8080",
    HTTP: &boot.HTTPOptions{},
})
```

--------------------------------

### Swagger Setup Commands

Source: https://spine.na2ru2.me/ko/learn/tutorial/8-swagger.html

Essential commands for installing and configuring Swagger.

```text
go install github.com/swaggo/swag/cmd/swag@latest
```

```text
// @Summary, // @Param, // @Router 등
```

```text
swag init
```

```text
e.GET("/swagger/*", ...)
```

```text
http://localhost:8080/swagger/index.html
```

--------------------------------

### GlobalPrefix validation examples

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Examples of valid and invalid GlobalPrefix configurations that trigger panics.

```go
// ✓ 유효
HTTP: &boot.HTTPOptions{GlobalPrefix: "/api/v1"}
HTTP: &boot.HTTPOptions{GlobalPrefix: "/v2"}

// ✗ panic 발생
HTTP: &boot.HTTPOptions{GlobalPrefix: "api"}       // '/'로 시작하지 않음
HTTP: &boot.HTTPOptions{GlobalPrefix: "/api/:ver"}  // Path 파라미터 포함
HTTP: &boot.HTTPOptions{GlobalPrefix: "/api/*"}     // 와일드카드 포함
```

--------------------------------

### Run Application

Source: https://spine.na2ru2.me/ko/reference/examples/login.html

Command to start the Go application.

```bash
go run .
```

--------------------------------

### Run Application

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Starts the application including HTTP, WebSocket, and consumer runtimes.

```go
Run(opts boot.Options) error
```

```go
if err := app.Run(boot.Options{
    Address: ":8080",
    HTTP: &boot.HTTPOptions{},
}); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### PostHandle Implementation Example

Source: https://spine.na2ru2.me/ko/reference/api/interceptor.html

Example of a logging interceptor that logs successful responses.

```go
func (i *LoggingInterceptor) PostHandle(ctx core.ExecutionContext, meta core.HandlerMeta) {
    log.Printf("[RES] %s %s OK", ctx.Method(), ctx.Path())
}
```

--------------------------------

### Initialize Application with Kafka

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Example of configuring the application to use Kafka for event consumption and production.

```go
app.Run(boot.Options{
    Address: ":8080",
    Kafka: &boot.KafkaOptions{
        Brokers: []string{"localhost:9092"},
        Read: &boot.KafkaReadOptions{
            GroupID: "my-consumer-group",
        },
        Write: &boot.KafkaWriteOptions{
            TopicPrefix: "myapp.",
        },
    },
    HTTP: &boot.HTTPOptions{},
})
```

--------------------------------

### Configure and run the application

Source: https://spine.na2ru2.me/ko/reference/examples/crud.html

Sets up dependency injection, registers routes, configures CORS, and starts the server.

```go
// main.go
package main

import (
    "log"
    "time"

    "github.com/NARUBROWN/spine"
    "github.com/NARUBROWN/spine/interceptor/cors"
    "github.com/NARUBROWN/spine/pkg/boot"

    "spine-user-demo/controller"
    "spine-user-demo/repository"
    "spine-user-demo/service"
)

func main() {
    app := spine.New()

    // 생성자 등록
    app.Constructor(
        repository.NewUserRepository,
        service.NewUserService,
        controller.NewUserController,
    )

    // 라우트 등록
    app.Route("GET", "/users", (*controller.UserController).List)
    app.Route("GET", "/users/:id", (*controller.UserController).GetByID)
    app.Route("POST", "/users", (*controller.UserController).Create)
    app.Route("PUT", "/users/:id", (*controller.UserController).Update)
    app.Route("DELETE", "/users/:id", (*controller.UserController).Delete)

    // Interceptor 등록
    app.Interceptor(
        cors.New(cors.Config{
            AllowOrigins: []string{"*"},
            AllowMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
            AllowHeaders: []string{"Content-Type"},
        }),
    )

    // 앱 시작
    if err := app.Run(boot.Options{
		Address:                ":8080",
		EnableGracefulShutdown: true,
		ShutdownTimeout:        10 * time.Second,
		HTTP: &boot.HTTPOptions{},
	}); err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Controller usage examples

Source: https://spine.na2ru2.me/ko/reference/api/query-values.html

Examples of using query.Values within controller methods.

```go
func (c *UserController) Search(q query.Values) []User {
    status := q.String("status")
    page := q.Int("page", 1)
    size := q.Int("size", 20)
    active := q.GetBoolByKey("active", true)
    
    return c.repo.Search(status, page, size, active)
}
```

```go
func (c *ProductController) Filter(q query.Values) []Product {
    filters := make(map[string]string)
    
    if q.Has("category") {
        filters["category"] = q.String("category")
    }
    if q.Has("min_price") {
        filters["min_price"] = q.String("min_price")
    }
    
    return c.repo.FindByFilters(filters)
}
```

--------------------------------

### Initialize Application with RabbitMQ

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Example of configuring the application to use RabbitMQ for event consumption and production.

```go
app.Run(boot.Options{
    Address: ":8080",
    RabbitMQ: &boot.RabbitMqOptions{
        URL: "amqp://guest:guest@localhost:5672/",
        Read: &boot.RabbitMqReadOptions{
            Exchange: "stock-exchange",
        },
        Write: &boot.RabbitMqWriteOptions{
            Exchange: "stock-exchange",
        },
    },
    HTTP: &boot.HTTPOptions{},
})
```

--------------------------------

### PreHandle Implementation Example

Source: https://spine.na2ru2.me/ko/reference/api/interceptor.html

Example of an authentication interceptor that validates tokens and aborts the pipeline if unauthorized.

```go
func (i *AuthInterceptor) PreHandle(ctx core.ExecutionContext, meta core.HandlerMeta) error {
    token := ctx.Header("Authorization")
    if token == "" {
        return httperr.Unauthorized("인증이 필요합니다")
    }
    
    user, err := i.auth.Validate(token)
    if err != nil {
        return httperr.Unauthorized("유효하지 않은 토큰입니다")
    }
    
    ctx.Set("auth.user", user)
    return nil
}
```

--------------------------------

### Creating a New Application Instance

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Initializes a new Spine application instance and starts the server.

```go
func New() App
```

```go
app := spine.New()
app.Run(boot.Options{
    Address: ":8080",
    HTTP: &boot.HTTPOptions{},
})
```

--------------------------------

### Initialize Spine Application

Source: https://spine.na2ru2.me/ko

Registers constructors for dependency injection and starts the HTTP server.

```go
// main.go
func main() {
    app := spine.New()
    
    // ✅ 생성자만 등록하면 의존성 자동 해결
    // ✅ 순서 상관없이 등록 가능
    app.Constructor(NewUserRepository, NewUserService, NewUserController)
    
    routes.RegisterUserRoutes(app)
    app.Run(boot.Options{
		Address:                ":8080",
		EnableGracefulShutdown: true,
		ShutdownTimeout:        10 * time.Second,
		HTTP: &boot.HTTPOptions{},
	})
}
```

--------------------------------

### HTTP Route Examples

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Demonstrates registering standard and nested routes using controller methods.

```go
// 기본 라우트
app.Route("GET", "/users", (*UserController).List)
app.Route("GET", "/users/:id", (*UserController).GetUser)
app.Route("POST", "/users", (*UserController).CreateUser)
app.Route("PUT", "/users/:id", (*UserController).UpdateUser)
app.Route("DELETE", "/users/:id", (*UserController).DeleteUser)

// 중첩 경로
app.Route("GET", "/users/:userId/posts/:postId", (*PostController).GetPost)
```

--------------------------------

### Install Spine Framework

Source: https://spine.na2ru2.me/ko/learn/getting-started/intro.html

Command to install the Spine package via Go modules.

```bash
go get github.com/NARUBROWN/spine
```

--------------------------------

### Example Controller Implementation

Source: https://spine.na2ru2.me/ko/learn/core-concepts/pipeline.html

Demonstrates a business logic controller that remains decoupled from HTTP and pipeline concerns.

```go
func (c *UserController) GetUser(userId path.Int) (User, error) {
    if userId.Value <= 0 {
        return User{}, httperr.BadRequest("유효하지 않은 사용자 ID")
    }
    return c.repo.FindByID(userId.Value)
}
```

--------------------------------

### Initialize a Spine Application

Source: https://spine.na2ru2.me/ko/learn/getting-started/intro.html

Demonstrates the basic setup of a Spine application, including dependency registration, interceptor configuration, routing, and server execution.

```go
func main() {
    app := spine.New()
    
    // 의존성 등록 — 순서 상관없이, 생성자만 등록하면 자동 해결
    app.Constructor(NewUserRepository, NewUserService, NewUserController)
    
    // 인터셉터 — 실행 순서가 코드에 그대로 보임
    app.Interceptor(&TxInterceptor{}, &LoggingInterceptor{})
    
    // 라우트 — 어떤 메서드가 어떤 경로인지 명확
    app.Route("GET", "/users", (*UserController).GetUser)
    
    if err := app.Run(boot.Options{
		Address:                ":8080",
		EnableGracefulShutdown: true,
		ShutdownTimeout:        10 * time.Second,
		HTTP: &boot.HTTPOptions{},
	}); err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Initialize and Run Server

Source: https://spine.na2ru2.me/ko/reference/examples/login.html

Registers constructors, CORS interceptors, and routes for a Spine application before starting the server.

```go
// main.go
package main

import (
    "log"
    "time"

    "login-example/controller"
    "login-example/interceptor"
    "login-example/store"

    "github.com/NARUBROWN/spine"
    "github.com/NARUBROWN/spine/interceptor/cors"
    "github.com/NARUBROWN/spine/pkg/boot"
    "github.com/NARUBROWN/spine/pkg/route"
)

func main() {
    app := spine.New()

    // 생성자 등록
    app.Constructor(
        store.NewUserStore,
        controller.NewAuthController,
    )

    // 전역 인터셉터 — CORS
    app.Interceptor(
        cors.New(cors.Config{
            AllowOrigins: []string{"*"},
            AllowMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
            AllowHeaders: []string{"Content-Type", "Authorization"},
        }),
    )

    // 공개 라우트 — 인증 불필요
    app.Route("POST", "/signup", (*controller.AuthController).Signup)
    app.Route("POST", "/login", (*controller.AuthController).Login)

    // 보호된 라우트 — 인증 필요 (라우트 인터셉터 사용)
    app.Route(
        "GET",
        "/me",
        (*controller.AuthController).GetMe,
        route.WithInterceptors(&interceptor.AuthInterceptor{}),
    )

    log.Println("서버 시작: http://localhost:8080")
    if err := app.Run(boot.Options{
		Address:                ":8080",
		EnableGracefulShutdown: true,
		ShutdownTimeout:        10 * time.Second,
		HTTP: &boot.HTTPOptions{},
	}); err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Multipart Upload Request Example

Source: https://spine.na2ru2.me/ko/learn/tutorial/2-controller.html

Example curl command to upload multiple files.

```bash
curl -X POST http://localhost:8080/upload \
  -F "file=@test1.png" \
  -F "file=@test2.jpg"
```

--------------------------------

### Run()

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Starts the application, including the HTTP server, WebSocket runtime, event consumer runtime, and custom transports.

```APIDOC
## Run()

### Description
Starts the application runtime. This method initializes and runs the HTTP server, WebSocket runtime, event consumer runtime, and any custom transports.

### Signature
`Run(opts boot.Options) error`

### Parameters
- `opts` (boot.Options) - Configuration options for the application bootstrap.

### Returns
- `error` - Returns an error if the server fails to start.

### Example
```go
if err := app.Run(boot.Options{
    Address: ":8080",
    HTTP: &boot.HTTPOptions{},
}); err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### Select query.Values or query.Pagination

Source: https://spine.na2ru2.me/ko/learn/core-concepts/query-values.html

Examples showing when to use query.Pagination for fixed pagination versus query.Values for dynamic queries.

```go
// 고정된 페이지네이션만 필요 → query.Pagination
func List(p query.Pagination) []User

// 동적 필터 + 페이지네이션 → 둘 다 사용
func Search(p query.Pagination, q query.Values) []User

// 완전히 동적인 쿼리 → query.Values만
func CustomSearch(q query.Values) []User
```

--------------------------------

### HTTP Response Examples

Source: https://spine.na2ru2.me/ko/learn/core-concepts/httperr.html

Expected JSON responses for various request scenarios.

```bash
# 잘못된 ID
GET /users/-1
→ 400 {"message": "유효하지 않은 사용자 ID입니다"}

# 존재하지 않는 사용자
GET /users/999
→ 404 {"message": "사용자를 찾을 수 없습니다"}

# 정상
GET /users/123
→ 200 {"id": 123, "name": "john"}
```

--------------------------------

### Run Services and Test API

Source: https://spine.na2ru2.me/ko/reference/examples/msa.html

Commands to start the services and verify the event flow via curl.

```bash
cd stock-app
go run main.go
```

```bash
cd order-app
go run main.go
```

```bash
curl -X POST http://localhost:8080/orders/12345
```

--------------------------------

### Get method

Source: https://spine.na2ru2.me/ko/reference/api/query-values.html

Retrieves the first value associated with the given key.

```go
func (q Values) Get(key string) string
```

```go
// GET /users?name=john
q.Get("name")     // "john"
q.Get("missing")  // ""
```

--------------------------------

### Automate Swagger Generation with Shell Script

Source: https://spine.na2ru2.me/ko/learn/tutorial/8-swagger.html

Use a shell script to initialize Swagger documentation and start the application.

```bash
#!/bin/bash
# run.sh

swag init -g main.go
go run main.go
```

```bash
chmod +x run.sh
./run.sh
```

--------------------------------

### Returning JSON and String Responses

Source: https://spine.na2ru2.me/ko/learn/tutorial/2-controller.html

Examples of returning basic JSON objects or plain strings using httpx.Response.

```go
func (c *UserController) GetUser(
    ctx context.Context,
    userId path.Int,
) httpx.Response[dto.UserResponse] {
    user, _ := c.svc.Get(ctx, int(userId.Value))
    
    return httpx.Response[dto.UserResponse]{
        Body: user,  // 200 OK (기본값)
    }
}
```

```go
func (c *UserController) Health() httpx.Response[string] {
    return httpx.Response[string]{
        Body: "OK",
    }
}
```

--------------------------------

### Implement Custom Domain Event

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Example implementation of a domain event struct satisfying the DomainEvent interface.

```go
type OrderCreated struct {
    OrderID int64     `json:"order_id"`
    At      time.Time `json:"at"`
}

func (e OrderCreated) Name() string {
    return "order.created"
}

func (e OrderCreated) OccurredAt() time.Time {
    return e.At
}
```

--------------------------------

### Automatic Struct Binding (Other Frameworks)

Source: https://spine.na2ru2.me/ko/learn/core-concepts/query-values.html

Example of the automatic struct-based binding pattern used by other frameworks, which Spine avoids.

```go
// 다른 프레임워크의 방식
type SearchParams struct {
    Status string   `query:"status"`
    Tags   []string `query:"tag"`
    Page   int      `query:"page"`
}

func Search(params SearchParams) { ... }
```

--------------------------------

### Retrieve Query Values as Strings

Source: https://spine.na2ru2.me/ko/learn/core-concepts/query-values.html

Use Get to fetch the first value of a key as a string. Returns an empty string if the key is missing.

```go
// GET /users?name=john&status=active

q.Get("name")    // "john"
q.Get("status")  // "active"
q.Get("missing") // ""
```

--------------------------------

### Skip Transactions by Method Name

Source: https://spine.na2ru2.me/ko/learn/tutorial/6-transaction.html

Conditionally skips transaction initiation for methods starting with specific prefixes like 'Get' or 'List'.

```go
func (i *TxInterceptor) PreHandle(ctx core.ExecutionContext, meta core.HandlerMeta) error {
    methodName := meta.Method.Name
    
    // Get으로 시작하는 메서드는 트랜잭션 스킵
    if strings.HasPrefix(methodName, "Get") || strings.HasPrefix(methodName, "List") {
        return nil
    }
    
    // 트랜잭션 시작
    tx, err := i.db.BeginTx(ctx.Context(), nil)
    if err != nil {
        return err
    }
    
    ctx.Set("tx", tx)
    return nil
}

func (i *TxInterceptor) AfterCompletion(ctx core.ExecutionContext, meta core.HandlerMeta, err error) {
    v, ok := ctx.Get("tx")
    if !ok {
        return  // 트랜잭션 없으면 스킵
    }
    
    tx := v.(*bun.Tx)
    if err != nil {
        tx.Rollback()
    } else {
        tx.Commit()
    }
}
```

--------------------------------

### Form DTO Request Example

Source: https://spine.na2ru2.me/ko/learn/tutorial/2-controller.html

Example curl command to submit form data.

```bash
curl -X POST http://localhost:8080/posts \
  -F "title=hello" \
  -F "content=spine"
```

--------------------------------

### GET /users

Source: https://spine.na2ru2.me/ko/reference/examples/crud.html

Retrieves a list of all users.

```APIDOC
## GET /users

### Description
Returns a list of all registered users.

### Method
GET

### Endpoint
http://localhost:8080/users

### Response
#### Success Response (200)
- **users** (array) - List of user objects
- **total** (integer) - Total count of users

#### Response Example
{
  "users": [
    {
      "id": 1,
      "name": "홍길동",
      "email": "hong@example.com",
      "created_at": "2025-01-19T10:00:00Z",
      "updated_at": "2025-01-19T10:00:00Z"
    }
  ],
  "total": 1
}
```

--------------------------------

### Initialize Application in main.go

Source: https://spine.na2ru2.me/ko/learn/tutorial/1-project-structure.html

The entry point for the application where constructors, interceptors, and routes are registered.

```go
package main

import (
    "log"
    "time"

    "github.com/NARUBROWN/spine"
    "github.com/NARUBROWN/spine/pkg/boot"
)

func main() {
    app := spine.New()

    // 1. 생성자 등록
    app.Constructor(
        NewDB,
        repository.NewUserRepository,
        service.NewUserService,
        controller.NewUserController,
        interceptor.NewTxInterceptor,
    )

    // 2. 인터셉터 등록
    app.Interceptor(
        (*interceptor.TxInterceptor)(nil),
        &interceptor.LoggingInterceptor{},
    )

    // 3. 라우트 등록
    routes.RegisterUserRoutes(app)

    // 4. 서버 시작
    if err := app.Run(boot.Options{
		Address:                ":8080",
		EnableGracefulShutdown: true,
		ShutdownTimeout:        10 * time.Second,
		HTTP: &boot.HTTPOptions{},
	}); err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### GET /users/{id}

Source: https://spine.na2ru2.me/ko/reference/examples/crud.html

Retrieves details for a specific user by ID.

```APIDOC
## GET /users/{id}

### Description
Fetches the details of a specific user identified by their ID.

### Method
GET

### Endpoint
http://localhost:8080/users/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the user

### Response
#### Success Response (200)
- **id** (integer) - User ID
- **name** (string) - User name
- **email** (string) - User email
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Update timestamp

#### Response Example
{
  "id": 1,
  "name": "홍길동",
  "email": "hong@example.com",
  "created_at": "2025-01-19T10:00:00Z",
  "updated_at": "2025-01-19T10:00:00Z"
}
```

--------------------------------

### Alias for String Retrieval

Source: https://spine.na2ru2.me/ko/learn/core-concepts/query-values.html

The String method acts as an alias for Get.

```go
q.String("name")  // "john"
```

--------------------------------

### Initialize Repository with bun.IDB

Source: https://spine.na2ru2.me/ko/learn/tutorial/5-database.html

Accept bun.IDB in the repository constructor to support both database connections and transactions.

```go
// repository/user_repository.go
package repository

import (
    "context"
    "myapp/entity"

    "github.com/uptrace/bun"
)

type UserRepository struct {
    db bun.IDB  // *bun.DB 또는 *bun.Tx 모두 가능
}

func NewUserRepository(db bun.IDB) *UserRepository {
    return &UserRepository{db: db}
}
```

--------------------------------

### Initialize Spine Application

Source: https://spine.na2ru2.me/ko/learn/tutorial/5-database.html

Configures the application entry point by registering constructors for database and service layers.

```go
// main.go
func main() {
    app := spine.New()
    
    app.Constructor(
        NewDB,                          // *bun.DB
        repository.NewUserRepository,   // bun.IDB → *UserRepository
        service.NewUserService,
        controller.NewUserController,
    )
    
    routes.RegisterUserRoutes(app)
    
    app.Run(boot.Options{
		Address:                ":8080",
		EnableGracefulShutdown: true,
		ShutdownTimeout:        10 * time.Second,
		HTTP: &boot.HTTPOptions{},
	})
```

--------------------------------

### Manage Internal Storage

Source: https://spine.na2ru2.me/ko/learn/core-concepts/execution-context.html

Uses Set and Get to share data between pipeline components.

```go
// Router에서 path params 저장
ctx.Set("spine.params", params)
ctx.Set("spine.pathKeys", keys)

// Adapter에서 ResponseWriter 저장
ctx.Set("spine.response_writer", NewEchoResponseWriter(c))

// Interceptor에서 조회
rw, ok := ctx.Get("spine.response_writer")
```

--------------------------------

### Warm-Up Controllers

Source: https://spine.na2ru2.me/ko/learn/core-concepts/handler-meta.html

Instantiate all controllers during the bootstrap phase.

```go
// internal/bootstrap/bootstrap.go
if err := container.WarmUp(router.ControllerTypes()); err != nil {
    panic(err)
}
```

--------------------------------

### Set Environment Variable and Run Application

Source: https://spine.na2ru2.me/ko/learn/tutorial/5-database.html

Export the database URL in the shell before executing the Go application.

```bash
export DATABASE_URL="user:password@tcp(localhost:3306)/mydb?parseTime=true&loc=Local"
go run main.go
```

--------------------------------

### Register Global Interceptors

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Defines the signature for registering global interceptors and provides an example of usage.

```go
Interceptor(interceptors ...core.Interceptor)
```

```go
app.Interceptor(
    cors.New(cors.Config{
        AllowOrigins: []string{"*"},
        AllowMethods: []string{"GET", "POST", "OPTIONS"},
        AllowHeaders: []string{"Content-Type"},
    }),
    &LoggingInterceptor{},
)
```

--------------------------------

### Skip Transactions by HTTP Method

Source: https://spine.na2ru2.me/ko/learn/tutorial/6-transaction.html

Excludes GET requests from transaction management to reduce overhead.

```go
func (i *TxInterceptor) PreHandle(ctx core.ExecutionContext, meta core.HandlerMeta) error {
    // GET 요청은 트랜잭션 스킵
    if ctx.Method() == "GET" {
        return nil
    }
    
    tx, err := i.db.BeginTx(ctx.Context(), nil)
    if err != nil {
        return err
    }
    
    ctx.Set("tx", tx)
    return nil
}
```

--------------------------------

### Registering Components by Domain

Source: https://spine.na2ru2.me/ko/learn/tutorial/3-dependency-injection.html

Organize application components by domain using app.Constructor calls.

```go
func main() {
    app := spine.New()
    
    // 인프라
    app.Constructor(
        NewDB,
        NewRedisClient,
        NewLogger,
    )
    
    // User 도메인
    app.Constructor(
        repository.NewUserRepository,
        service.NewUserService,
        controller.NewUserController,
    )
    
    // Order 도메인
    app.Constructor(
        repository.NewOrderRepository,
        service.NewOrderService,
        controller.NewOrderController,
    )
    
    if err := app.Run(boot.Options{
		Address:                ":8080",
		EnableGracefulShutdown: true,
		ShutdownTimeout:        10 * time.Second,
		HTTP: &boot.HTTPOptions{},
	}); err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Configure Order Service Application

Source: https://spine.na2ru2.me/ko/reference/examples/msa.html

Initialize the application and configure Kafka broker settings for event publishing.

```go
// order-app/main.go
package main

import (
    "log"
    "time"

    "github.com/NARUBROWN/spine"
    "github.com/your-org/spine-simple-msa/order-app/controller"
    "github.com/NARUBROWN/spine/pkg/boot"
)

func main() {
    app := spine.New()

    app.Constructor(
        controller.NewOrderController,
    )

    app.Route(
        "POST",
        "/orders/:order_id",
        (*controller.OrderController).Create,
    )

    if err := app.Run(boot.Options{
        Address:                ":8080",
        EnableGracefulShutdown: true,
        ShutdownTimeout:        10 * time.Second,
        Kafka: &boot.KafkaOptions{
            Brokers: []string{"localhost:9092"},
            Write: &boot.KafkaWriteOptions{
                TopicPrefix: "",
            },
        },
        HTTP: &boot.HTTPOptions{},
    }); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Interceptor implementation with ExecutionContext

Source: https://spine.na2ru2.me/ko/learn/core-concepts/execution-context.html

Example of an interceptor accessing the ExecutionContext to retrieve the ResponseWriter and handle CORS logic.

```go
// interceptor/cors/cors.go
func (i *CORSInterceptor) PreHandle(ctx core.ExecutionContext, meta core.HandlerMeta) error {
    // ResponseWriter 획득
    rwAny, ok := ctx.Get("spine.response_writer")
    if !ok {
        return nil
    }
    rw := rwAny.(core.ResponseWriter)
    
    // 요청 정보 확인
    origin := ctx.Header("Origin")
    if origin != "" && i.isAllowedOrigin(origin) {
        rw.SetHeader("Access-Control-Allow-Origin", origin)
    }
    
    // Preflight 처리
    if ctx.Method() == "OPTIONS" {
        rw.WriteStatus(204)
        return core.ErrAbortPipeline
    }
    
    return nil
}
```

--------------------------------

### Configure Database Connection with Environment Variables

Source: https://spine.na2ru2.me/ko/learn/tutorial/5-database.html

Use os.Getenv to retrieve the database URL, falling back to a default string if not set.

```go
// db.go
import "os"

func NewDB() *bun.DB {
    dsn := os.Getenv("DATABASE_URL")
    if dsn == "" {
        dsn = "user:password@tcp(localhost:3306)/mydb?parseTime=true&loc=Local"
    }
    
    sqldb, err := sql.Open("mysql", dsn)
    if err != nil {
        panic(err)
    }
    
    return bun.NewDB(sqldb, mysqldialect.New())
}
```

--------------------------------

### Constructor-based Dependency Injection

Source: https://spine.na2ru2.me/ko/learn/getting-started/intro.html

Shows how to define dependencies using constructor parameters and register them with the application container.

```go
// 생성자 파라미터가 곧 의존성 선언
func NewUserService(repo *UserRepository) *UserService {
    return &UserService{repo: repo}
}

// 등록만 하면 자동으로 의존성 그래프 해결
app.Constructor(NewUserRepository, NewUserService, NewUserController)
```

--------------------------------

### Get User Profile API Request

Source: https://spine.na2ru2.me/ko/reference/examples/login.html

Retrieves user information, requiring a valid Authorization header.

```bash
curl http://localhost:8080/me
```

```json
{
  "message": "토큰이 필요합니다."
}
```

```bash
curl http://localhost:8080/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

```json
{
  "id": 1,
  "email": "alice@example.com",
  "name": "Alice"
}
```

--------------------------------

### Implement User Repository

Source: https://spine.na2ru2.me/ko/reference/examples/crud.html

sync.RWMutex를 사용하여 인메모리 맵 기반의 데이터 저장소 및 CRUD 연산을 구현합니다.

```go
// repository/user_repository.go
package repository

import (
    "errors"
    "sync"
    "time"

    "spine-user-demo/model"
)

var (
    ErrUserNotFound      = errors.New("user not found")
    ErrEmailAlreadyExists = errors.New("email already exists")
)

type UserRepository struct {
    mu      sync.RWMutex
    users   map[int64]*model.User
    counter int64
}

func NewUserRepository() *UserRepository {
    return &UserRepository{
        users:   make(map[int64]*model.User),
        counter: 0,
    }
}

func (r *UserRepository) FindAll() []*model.User {
    r.mu.RLock()
    defer r.mu.RUnlock()

    result := make([]*model.User, 0, len(r.users))
    for _, user := range r.users {
        result = append(result, user)
    }
    return result
}

func (r *UserRepository) FindByID(id int64) (*model.User, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()

    user, ok := r.users[id]
    if !ok {
        return nil, ErrUserNotFound
    }
    return user, nil
}

func (r *UserRepository) FindByEmail(email string) (*model.User, error) {
    r.mu.RLock()
    defer r.mu.RUnlock()

    for _, user := range r.users {
        if user.Email == email {
            return user, nil
        }
    }
    return nil, ErrUserNotFound
}

func (r *UserRepository) ExistsByEmail(email string) bool {
    _, err := r.FindByEmail(email)
    return err == nil
}

func (r *UserRepository) Save(user *model.User) *model.User {
    r.mu.Lock()
    defer r.mu.Unlock()

    now := time.Now()

    if user.ID == 0 {
        r.counter++
        user.ID = r.counter
        user.CreatedAt = now
    }
    user.UpdatedAt = now

    r.users[user.ID] = user
    return user
}

func (r *UserRepository) Delete(id int64) error {
    r.mu.Lock()
    defer r.mu.Unlock()

    if _, ok := r.users[id]; !ok {
        return ErrUserNotFound
    }

    delete(r.users, id)
    return nil
}

func (r *UserRepository) Count() int {
    r.mu.RLock()
    defer r.mu.RUnlock()
    return len(r.users)
}
```

--------------------------------

### TxInterceptor 구현

Source: https://spine.na2ru2.me/ko/learn/tutorial/6-transaction.html

bun.DB를 사용하여 트랜잭션을 시작하고 ExecutionContext에 저장한 뒤, 요청 완료 시 커밋 또는 롤백을 처리하는 인터셉터 구현입니다.

```go
// interceptor/tx_interceptor.go
package interceptor

import (
    "errors"

    "github.com/NARUBROWN/spine/core"
    "github.com/uptrace/bun"
)

type TxInterceptor struct {
    db *bun.DB
}

// 생성자 — DB 의존성 주입
func NewTxInterceptor(db *bun.DB) *TxInterceptor {
    return &TxInterceptor{db: db}
}

// PreHandle — 트랜잭션 시작
func (i *TxInterceptor) PreHandle(ctx core.ExecutionContext, meta core.HandlerMeta) error {
    reqCtx := ctx.Context()
    if reqCtx == nil {
        return errors.New("execution context has no request context")
    }

    // 트랜잭션 시작
    tx, err := i.db.BeginTx(reqCtx, nil)
    if err != nil {
        return err
    }

    // ExecutionContext에 저장
    ctx.Set("tx", tx)
    return nil
}

// PostHandle — 아무것도 안 함
func (i *TxInterceptor) PostHandle(ctx core.ExecutionContext, meta core.HandlerMeta) {}

// AfterCompletion — 커밋 또는 롤백
func (i *TxInterceptor) AfterCompletion(ctx core.ExecutionContext, meta core.HandlerMeta, err error) {
    v, ok := ctx.Get("tx")
    if !ok {
        return
    }

    tx, ok := v.(bun.Tx)
    if !ok {
        return
    }

    // 에러 여부에 따라 롤백/커밋
    if err != nil {
        _ = tx.Rollback()
    } else {
        _ = tx.Commit()
    }
}
```

--------------------------------

### 생성된 docs/docs.go 파일 예시

Source: https://spine.na2ru2.me/ko/learn/tutorial/8-swagger.html

자동 생성된 Swagger 문서 설정 파일의 구조입니다.

```go
// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs

import "github.com/swaggo/swag"

const docTemplate = `{
    "swagger": "2.0",
    "info": {
        "title": "My App API",
        "version": "1.0.0"
    },
    ...
}`

var SwaggerInfo = &swag.Spec{
    Version:     "1.0.0",
    Title:       "My App API",
    Description: "Spine 기반 REST API",
    // ...
}

func init() {
    swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
}
```

--------------------------------

### Access Method and Path by Protocol

Source: https://spine.na2ru2.me/ko/learn/core-concepts/execution-context.html

Demonstrates how Method() and Path() return different values based on the transport protocol.

```go
// HTTP
ctx.Method()  // "GET"
ctx.Path()    // "/users/123/posts/456"

// Consumer
ctx.Method()  // "EVENT"
ctx.Path()    // "order.created" (EventName)

// WebSocket
ctx.Method()  // "WS"
ctx.Path()    // WebSocket 경로
```

--------------------------------

### Configure Stock Service Application

Source: https://spine.na2ru2.me/ko/reference/examples/msa.html

Register consumers and configure Kafka read settings for the Stock Service.

```go
// stock-app/main.go
package main

import (
    "log"
    "time"

    "github.com/NARUBROWN/spine"
    "github.com/your-org/spine-simple-msa/stock-app/consumer"
    "github.com/NARUBROWN/spine/pkg/boot"
)

func main() {
    app := spine.New()

    app.Constructor(
        consumer.NewOrderConsumer,
    )

    // 컨슈머 등록
    if err := app.Consumers().Register(
        "order.created",
        (*consumer.OrderConsumer).OnCreated,
    ); err != nil {
        log.Fatal(err)
    }

    if err := app.Run(boot.Options{
        Address:                ":8081",
        EnableGracefulShutdown: true,
        ShutdownTimeout:        10 * time.Second,
        Kafka: &boot.KafkaOptions{
            Brokers: []string{"localhost:9092"},
            Read: &boot.KafkaReadOptions{
                GroupID: "stock-service",
            },
        },
        HTTP: &boot.HTTPOptions{},
    }); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### String(key string) string

Source: https://spine.na2ru2.me/ko/reference/api/query-values.html

Retrieves the first value associated with the specified key as a string. This is an alias for Get().

```APIDOC
## String(key string) string

### Description
Returns the first value associated with the specified key as a string.

### Parameters
- **key** (string) - Required - The query parameter key to retrieve.

### Returns
- **string** - The value associated with the key, or an empty string if not found.
```

--------------------------------

### Define Options structures

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

The main configuration structures for the application and HTTP settings.

```go
type Options struct {
    // 서버가 바인딩될 주소 (예: ":8080")
    Address string

    // Graceful Shutdown 활성화 여부
    EnableGracefulShutdown bool

    // Graceful Shutdown 시 최대 대기 시간
    ShutdownTimeout time.Duration

    // Kafka 이벤트 인프라 설정
    // nil인 경우 Kafka는 구성되지 않음
    Kafka *KafkaOptions

    // RabbitMQ 이벤트 인프라 설정
    // nil인 경우 RabbitMQ는 구성되지 않음
    RabbitMQ *RabbitMqOptions

    // HTTP Runtime 전용 설정
    // nil인 경우 HTTP 서버는 실행되지 않음
    HTTP *HTTPOptions
}

type HTTPOptions struct {
    // HTTP API 전역 Prefix (예: "/api/v1")
    // 빈 값이면 Prefix를 적용하지 않습니다.
    GlobalPrefix string

    // Recover 미들웨어 비활성화 여부 (기본: false = 활성화)
    DisableRecover bool
}
```

--------------------------------

### Run Application via CLI

Source: https://spine.na2ru2.me/ko

Execute the application directly using the Go toolchain without runtime initialization overhead.

```zsh
➜ spine-app go run .
```

--------------------------------

### Validating Handlers at Bootstrap

Source: https://spine.na2ru2.me/ko/learn/core-concepts/handler-meta.html

Invalid handler registrations cause the application to fail during the bootstrap phase before the server starts.

```go
// 잘못된 핸들러 등록 시 부트스트랩 실패
meta, err := spineRouter.NewHandlerMeta(invalidHandler)
if err != nil {
    return err  // 서버 시작 전 에러
}
```

--------------------------------

### Registering Global and Route Interceptors

Source: https://spine.na2ru2.me/ko/learn/tutorial/4-interceptor.html

Demonstrates how to register global interceptors using app.Interceptor and route-specific interceptors using route.WithInterceptors.

```go
// 전역 인터셉터
app.Interceptor(
    &interceptor.LoggingInterceptor{},   // 전역 1
    &interceptor.CORSInterceptor{},      // 전역 2
)

// 라우트 인터셉터
app.Route(
    "GET",
    "/users/:id",
    (*UserController).GetUser,
    route.WithInterceptors(&interceptor.AuthInterceptor{}),  // 라우트 1
)
```

--------------------------------

### Go 버전 확인

Source: https://spine.na2ru2.me/ko/learn/getting-started/installation.html

설치 전 시스템에 설치된 Go 버전을 확인합니다.

```bash
# Go 버전 확인
go version
```

--------------------------------

### Implement Repository Layer

Source: https://spine.na2ru2.me/ko/learn/tutorial/1-project-structure.html

Repositories handle direct database access, including SQL queries or ORM operations.

```go
// repository/user_repository.go
package repository

type UserRepository struct {
    db bun.IDB  // bun.DB 또는 bun.Tx 모두 수용
}

func NewUserRepository(db bun.IDB) *UserRepository {
    return &UserRepository{db: db}
}

func (r *UserRepository) FindByID(ctx context.Context, id int) (*entity.User, error) {
    user := new(entity.User)
    err := r.db.NewSelect().
        Model(user).
        Where("id = ?", id).
        Scan(ctx)
    return user, err
}

func (r *UserRepository) Save(ctx context.Context, user *entity.User) error {
    _, err := r.db.NewInsert().
        Model(user).
        Exec(ctx)
    return err
}
```

--------------------------------

### Register Custom Transports

Source: https://spine.na2ru2.me/ko/reference/api/spine-app.html

Defines the signature for registering custom transports and the interface requirements, followed by a gRPC implementation example.

```go
RegisterTransport(t core.CustomTransport)
```

```go
// core/transport.go
type CustomTransport interface {
    // Init은 DI Container 준비 이후 호출됩니다.
    Init(container Container) error
    // Start는 Init 이후 별도 goroutine에서 호출됩니다.
    Start() error
    // Stop은 Graceful Shutdown 시 호출됩니다.
    Stop(ctx context.Context) error
}

type Container interface {
    Resolve(t reflect.Type) (any, error)
}
```

```go
type GRPCTransport struct {
    server *grpc.Server
}

func (t *GRPCTransport) Init(container core.Container) error {
    // Container에서 서비스 Resolve
    svc, err := container.Resolve(reflect.TypeOf((*MyService)(nil)))
    if err != nil {
        return err
    }
    t.server = grpc.NewServer()
    RegisterMyServiceServer(t.server, svc.(*MyService))
    return nil
}

func (t *GRPCTransport) Start() error {
    lis, _ := net.Listen("tcp", ":9090")
    return t.server.Serve(lis)
}

func (t *GRPCTransport) Stop(ctx context.Context) error {
    t.server.GracefulStop()
    return nil
}

app.RegisterTransport(&GRPCTransport{})
```
Tokens:
Raw