spine-cli

command module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 2 Imported by: 0

README

Spine CLI

Spine CLI는 Spine 애플리케이션을 생성하고, 소스 코드에서 실행 계약을 검사하고 설명하며 검증하는 Go CLI입니다.

프로젝트 이름은 spine-cli입니다. 루트 경로로 설치하면 실행 파일은 spine-cli, cmd/spine 경로로 설치하면 실행 파일과 명령은 spine입니다.

  • 프로젝트와 domain, DTO, repository, service, controller, 메시지 구성 요소 생성
  • HTTP, DI, interceptor, consumer, WebSocket 실행 계약 검사
  • 계약 검증, snapshot/diff, OpenAPI와 AsyncAPI 내보내기

권장 환경과 설치

  • 권장 Go 버전: 1.27.3
  • 새 프로젝트가 사용하는 Spine 버전: v0.5.1
go install github.com/NARUBROWN/spine-cli@v0.2.0
spine-cli version
# spine-cli 0.2.0

짧은 spine 명령을 사용하려면 기존 cmd/spine 경로로 설치합니다.

go install github.com/NARUBROWN/spine-cli/cmd/spine@v0.2.0
spine version
# spine-cli 0.2.0

빠른 시작

spine new todo-api --module github.com/acme/todo-api
cd todo-api
go mod tidy
spine dev

다른 터미널에서 생성된 health endpoint를 확인합니다.

curl http://localhost:8080/health

새 프로젝트에는 명시적인 BuildApplication composition root, app.Validate, GET /health, spine.toml이 포함됩니다.

생성기

새 프로젝트는 layout = "layered-v1"을 사용합니다. 역할별 기본 경로 아래에 파일을 바로 두거나, 이름 앞에 선택적인 하위 경로를 지정할 수 있습니다.

역할 기본 경로 생성 내용
domain database/domain/ 명시한 필드만 포함하는 타입
repository database/repository/ 구조체와 생성자
DTO src/dto/ JSON 태그가 있는 타입
service src/service/ 구조체와 생성자
controller src/controller/ 구조체와 생성자
route src/route/route.go 명시한 HTTP 메서드와 경로 등록
application internal/application/ 생성자와 등록 함수 연결
spine g domain account/user --field id:int64 --field name:string
spine g dto account/create-user-request --field name:string
spine g repository account/user
spine g service user --depends database/repository/account:UserRepository
spine g controller admin/user --depends src/service:UserService

domain user는 database/domain/user.go, domain account/user는 database/domain/account/user.go를 생성합니다. commerce/account/user처럼 여러 단계로 묶을 수도 있습니다. 그룹은 역할마다 독립적으로 정하며 실행 위치는 생성 경로에 영향을 주지 않습니다. CLI는 그룹을 애그리거트로 해석하지 않습니다.

--depends는 모듈 기준 패키지 경로와 타입을 받습니다. 여러 의존성은 옵션을 반복해서 지정합니다. CLI는 실제 타입과 단일 공개 생성자를 확인하고 import와 생성자 인자와 application 등록을 연결합니다. 서로 다른 패키지의 동명 타입도 구분합니다. domain과 DTO는 DI에 등록하지 않습니다. repository에는 DB 연결이나 CRUD 구현을 추가하지 않습니다.

controller 생성만으로 HTTP 경로가 생기지는 않습니다. 실제 Get 메서드를 작성한 뒤 등록합니다.

# src/controller/admin 패키지에 UserController.Get 메서드가 있을 때 실행
spine g route get-user --method GET --path /users/:id \
  --handler src/controller/admin:UserController.Get

Get은 경로의 id를 받는 핸들러여야 합니다. 예를 들어 Spine의 path.Int 매개변수를 사용할 수 있습니다. CLI는 메서드 존재와 경로 바인딩과 기존 경로 충돌을 확인합니다.

spine g resource account/user는 같은 그룹의 domain, repository, service, controller 생성을 조합합니다. DTO와 HTTP 경로는 별도로 추가합니다. 생성자는 기본적으로 application에 등록하며, 파일만 생성하려면 --no-register를 사용합니다.

consumer와 WebSocket 생성기도 사용할 수 있습니다.

spine g consumer order --topic order.created --field order_id:int64
spine g websocket chat --path /ws/chat --field message:string

생성한 메시지 핸들러는 not implemented 오류를 반환합니다. 실제 로직을 작성하고 이 오류를 제거한 뒤 검증하세요. transport와 재시도와 WebSocket 접근 정책은 애플리케이션에서 구성합니다.

layout이 없는 기존 프로젝트와 layout = "legacy" 프로젝트에는 이전 생성 규칙을 적용합니다. 기존 파일을 이동하거나 구조를 자동 전환하지 않습니다. 이전 구조의 재현이 필요하면 spine new <project> --layout legacy를 사용할 수 있습니다. slice --storage memory는 legacy에서만 지원하며, 새 구조에 CRUD 생성 기능을 추가하지 않습니다.

실행 계약

# 현재 등록 계약 조회와 단일 실행 경로 설명
spine inspect
spine explain http GET /orders/:id
spine explain consumer order.created
spine explain websocket /ws/orders

# CI 또는 로컬 검증
spine contract check --warnings-as-errors
spine verify

# 의미 단위 계약 변경 추적
spine contract snapshot
spine contract diff

# API 문서 생성
spine contract export --format openapi --output openapi.json
spine contract export --format asyncapi --output asyncapi.json

검증 결과는 다음 경계를 가집니다.

  • inspect, explain, contract check는 정적 소스 분석입니다.
  • 등록 이름의 문자열·문자열 연결·직접적인 os.Getenv("이름") 호출과, 이 문자열의 ==/!= 조건은 검사 프로세스의 환경변수로 해석합니다. 검사와 앱 실행에 같은 값을 전달해야 합니다.
  • 임의 함수·지역 변수·환경변수 변경 호출은 평가하지 않으며, 해석하지 못한 등록은 계속 오류로 처리합니다.
  • 분석할 수 없는 조건부 등록과 동적 등록, 현재 모듈 밖의 Register(app) 호출은 오류와 analysis_complete: false로 표시합니다.
  • contract probe는 BuildApplication, app.Validate, consumer/WebSocket 공개 registry만 대조합니다.
  • verify 성공은 계약·gofmt·vet·test의 로컬 통과를 뜻합니다. DB, broker, listener, 배포 환경의 정상 동작은 별도의 E2E 검증이 필요합니다.

OpenAPI와 AsyncAPI는 타입을 선언한 패키지와 import 범위를 기준으로 스키마를 구분합니다. JSON 태그가 없으면 Go 필드 이름을 그대로 사용하고, time.Time은 string과 date-time으로 표현합니다. 해석할 수 없는 타입은 x-spine-unresolved-type으로 표시합니다. 이 표시는 문서의 분석 한계이며 실제 API의 요청 필드가 아닙니다. AsyncAPI의 채널과 operation 식별자는 원래 이름을 구분하도록 만들며, 문서에 기록된 참조를 사용해야 합니다.

개발 명령

명령 동작
spine dev 변경을 감지하고, 새 빌드가 성공한 경우에만 앱을 교체
spine run ENV=production으로 빌드하고 실행
spine test go test ./... 실행
spine check gofmt 상태, go vet, go test 검사
spine verify 정적 계약 검사 후 spine check 수행
spine build bin/<모듈명>에 바이너리 생성
spine doctor 도구 체인, 설정, 정적 계약을 오프라인 진단
spine completion <shell> bash, zsh, PowerShell completion 생성

run, test, check, build는 --help 또는 -h로 도움말을 확인할 수 있습니다. 그 밖의 명령별 옵션은 실행 전에 오류로 처리합니다. 테스트 필터는 go test ./... -run <이름>으로 직접 실행하세요.

run은 매번 go build를 호출해 Go 자체의 빌드 캐시와 로컬 의존성 변경을 반영합니다. dev는 Go가 열거한 소스와 embed 파일, 모듈과 프로젝트 설정을 감시합니다. 일반 로그 기록은 재시작 조건에서 제외하며 유효한 설정 변경 시 새 포트를 전달합니다. SIGTERM에서도 자식 앱을 종료하고 회수합니다.

프로젝트 설정

spine.toml은 CLI가 읽는 프로젝트 설정 파일입니다.

module = "github.com/acme/todo-api"
entrypoint = "."
composition = "./internal/application"
port = 8080
layout = "layered-v1"

module은 go.mod의 module path와 같아야 합니다.

안전한 생성

생성기는 기존 파일을 기본적으로 덮어쓰지 않습니다. 먼저 변경 계획을 확인하고, 의도적인 교체에만 --force를 사용하세요.

spine g resource orders --dry-run
spine g resource orders --dry-run --json
spine g resource orders --if-match <base_hash> --json

JSON dry-run에는 모든 변경 파일과 diff와 SHA-256, base_hash가 포함됩니다. 새 구조의 g는 대상 파일뿐 아니라 분석한 Go 소스와 모듈 파일과 spine.toml, 생성할 내용도 해시에 포함합니다. 소스의 직접적인 os.Getenv("이름") 호출이 참조하는 환경 값도 변경 검사에 포함하며 값 자체는 출력하지 않습니다. 검토 후 입력이나 계획이 달라지면 --if-match 적용을 중단합니다. 동일한 요청은 import와 생성자와 경로를 중복 등록하지 않습니다.

AI Agent에서 사용하기

명령 스키마, JSON 프로토콜, 안전한 생성 절차, 정확한 증거 범위와 저장소 구조는 llms.txt를 참고하세요.

spine schema --json
spine context --json

저장소 개발

GOCACHE=/tmp/spine-cli-gocache go test -race ./...
GOCACHE=/tmp/spine-cli-gocache go vet ./...
git diff --check

License

MIT

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
cmd
spine command
internal
cli

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL