API 서비스 만들기

이 가이드는 로그인과 프로필 엔드포인트가 있는 간단한 user service를 만듭니다. .api DSL 파일을 작성하고, 프로젝트를 생성한 뒤, 비즈니스 로직을 채웁니다.

1단계 — API DSL 작성

디렉터리를 만들고 DSL을 작성합니다.

mkdir user-api && cd user-api

user.api를 만듭니다.

syntax = "v1"

type (
    LoginReq {
        Username string `json:"username"`
        Password string `json:"password"`
    }

    LoginResp {
        Token string `json:"token"`
    }

    UserInfoReq {
        Id int64 `path:"id"`
    }

    UserInfoResp {
        Id       int64  `json:"id"`
        Username string `json:"username"`
        Email    string `json:"email"`
    }
)

service user-api {
    @handler Login
    post /user/login (LoginReq) returns (LoginResp)

    @handler GetUserInfo
    get /user/:id (UserInfoReq) returns (UserInfoResp)
}

2단계 — 서비스 생성

goctl api go -api user.api -dir .
go mod init user-api
go mod tidy

생성되는 구조는 다음과 같습니다.

user-api/
├── etc/
│   └── user-api.yaml
├── internal/
│   ├── config/config.go
│   ├── handler/
│   │   ├── loginhandler.go         # 예시입니다
│   │   ├── getuserinfohandler.go   # 예시입니다
│   │   └── routes.go
│   ├── logic/
│   │   ├── loginlogic.go           # 예시입니다
│   │   └── getuserinfologic.go     # 예시입니다
│   ├── svc/servicecontext.go
│   └── types/types.go             # DSL 예시입니다
└── user.go

3단계 — 로직 구현

internal/logic/loginlogic.go를 수정합니다.

func (l *LoginLogic) Login(req *types.LoginReq) (resp *types.LoginResp, err error) {
    // In, DB, JWT 예시입니다
    if req.Username == "admin" && req.Password == "secret" {
        return &types.LoginResp{
            Token: "mock-jwt-token-for-" + req.Username,
        }, nil
    }
    return nil, errors.New("invalid credentials")
}

internal/logic/getuserinfologic.go도 수정합니다.

func (l *GetUserInfoLogic) GetUserInfo(req *types.UserInfoReq) (resp *types.UserInfoResp, err error) {
    // In, DB 예시입니다
    return &types.UserInfoResp{
        Id:       req.Id,
        Username: "alice",
        Email:    "alice@example.com",
    }, nil
}

4단계 — 실행과 테스트

go run user.go

다른 터미널에서 호출합니다.

# Login
curl -s -X POST http://localhost:8888/user/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"secret"}'
# 예시입니다

# 가져옵니다
curl http://localhost:8888/user/1
# 예시입니다

DSL 변경 후 다시 생성하기

user.api를 변경할 때마다 로직 파일을 덮어쓰지 않고 다시 생성할 수 있습니다.

goctl api go -api user.api -dir .

goctl은 자신이 소유한 파일(handler/, types/, routes.go)만 덮어씁니다. logic/ 파일은 보존됩니다.

다음 단계

• 엔드포인트 보호를 위해 JWT 미들웨어 추가
• 데이터베이스 모델 연결
• RPC 서비스 만들기 →