Skip to content

README.ko.md

Latest commit

 

History

History
150 lines (110 loc) · 6.79 KB

README.ko.md

File metadata and controls

150 lines (110 loc) · 6.79 KB
Raw

Channel App 튜토리얼 — Go

English | 한국어 | 日本語

공식 Channel App SDK로 만든 최소 end-to-end App Store 앱입니다. SDK가 Function registry, schema, command Extension, versioned HTTP route, auto-registration, token lifecycle, request signature 검증을 담당합니다.

이 저장소는 바로 실행할 수 있는 예제로 사용하고 계약과 설계 원칙은 SDK 문서를 확인하세요.

이 앱에서 확인할 수 있는 것

  • go.mod에 고정된 github.com/channel-io/app-sdk/go 버전
  • SDK builder로 등록하는 command Extension
  • Typed app Function과 생성되는 JSON Schema
  • SDK가 관리하는 app/channel token cache와 refresh
  • /functions/:version의 SDK Gin server
  • @channel.io/app-sdk-wam 0.17.2를 사용하는 React WAM
  • Go DTO와 TypeScript WAM data가 함께 검증하는 언어 중립 JSON Schema
  • @channel.io/bezier-react/beta의 Bezier 4 component

그룹 대화에서 /tutorial Desk command를 실행하면 WAM이 열립니다. WAM은 app bot 또는 현재 manager 권한으로 team-chat message를 보냅니다. 지원하지 않는 chat type에서는 조용히 닫지 않고 오류 상태를 보여 줍니다.

코드에서 핵심 개념은 다음과 대응합니다.

  • Extension: command builder가 versioned command capability metadata를 공개합니다.
  • Function: tutorial.open과 tutorial.sendAsBot은 command와 WAM이 참조하는 standalone typed operation입니다.
  • WAM: React UI는 /resource/wam/tutorial에서 제공됩니다. useCallFunction은 app server를, useNativeFunction은 현재 manager 주체로 Channel을 호출합니다.
  • 인증: SDK server가 inbound signature를 검증하고 native.TokenManager가 bot 경로의 channel token을 cache합니다. Server는 허용된 group-chat target에 짧은 signature를 붙여 WAM에 전달하며 manager authorization은 Channel host가 관리합니다.

Bot 경로는 native.TokenManager로 channel token을 얻고 native.ProxyAPI.WriteGroupMessage를 호출합니다. 앱이 Native Function HTTP transport를 직접 구현하지 않습니다.

SDK 계약

이 튜토리얼은 공개 SDK runtime 계약을 따릅니다.

  • SDK가 소유하는 typed Function/Extension discovery
  • PUT /functions/:version과 /functions/v1
  • Signature 검증과 SDK token lifecycle
  • Deploy 이후 AppStore Extension 등록
  • System version이 없는 bare PUT /functions를 같은 검증된 SDK handler로 연결하는 좁은 compatibility route

앱은 최신 Go SDK release를 고정하고 Function/WAM endpoint root를 직접 제공합니다.

준비 사항

  • Go 1.25
  • WAM용 Node.js와 Corepack 기반 Yarn 4
  • App ID, App Secret, Signing Key가 있는 개발용 private Channel App

앱이 아직 없다면 SDK의 첫 앱 만들기 Quickstart부터 따라 하세요. Private app 생성, server-side credential, 최소 permission, endpoint root, test channel 설치를 한 흐름으로 설명합니다.

인증 및 권한 설정에서 다음 permission을 활성화합니다.

  • Channel: writeGroupMessage
  • Manager: writeGroupMessageAsManager

Clone

git clone https://github.com/channel-io/app-tutorial.git
cd app-tutorial
corepack enable

환경 변수

cp .env.example .env

APP_ID, APP_SECRET, hex-encoded SIGNING_KEY를 입력하고 현재 shell에 불러옵니다.

set -a
. ./.env
set +a

Secret을 Git에 commit하지 마세요.

HTTPS endpoint

Local port 3022를 연결하는 HTTPS tunnel을 준비하고 개발자 포털에 다음 root를 저장합니다.

  • Function Endpoint: https://YOUR_HOST/functions
  • WAM Endpoint: https://YOUR_HOST/resource/wam

/v1이나 /tutorial을 덧붙이지 않습니다. Credential, permission, endpoint를 server 시작 뒤 바꿨다면 auto-registration이 다시 실행되도록 server를 재시작하세요.

SDK route는 versioned path를 사용합니다. 현재 command execution은 system version 없이 설정된 Function Endpoint를 호출할 수 있으므로 튜토리얼은 bare PUT /functions도 같은 SDK handler와 signature 검증으로 연결합니다.

Build와 실행

make build
make run

검증된 test suite만 따로 실행할 수 있습니다.

make test
설정 URL
Function Endpoint https://YOUR_HOST/functions
WAM Endpoint https://YOUR_HOST/resource/wam
Health check http://localhost:3022/ping
Local WAM http://localhost:3022/resource/wam/tutorial

Server가 시작되고 Extension 등록이 성공하면 test channel에서 private app을 설치하거나 새로고침한 뒤 그룹 대화에서 /tutorial을 실행하세요. 두 sender button과 permission failure를 모두 확인합니다. SKIP_SIGNATURE_VERIFICATION=true는 local debugging 밖에서 사용하지 마세요.

프로젝트 구조

cmd/main.go                         SDK server와 Extension auto-registration
cmd/function_endpoint.go            bare Function Endpoint compatibility route
internal/tutorial/app.go           command metadata와 typed app Function
internal/tutorial/contracts.go     public WAM contract의 Go type과 name
internal/tutorial/native_message.go SDK token manager와 typed ProxyAPI 호출
contracts/                         언어 중립 WAM wire schema
wam/src/contracts.ts               TypeScript view와 runtime validation
wam/src/pages/Send/Send.tsx         app/native call용 WAM SDK hook

현재 계약은 SDK guide와 reference에서 확인하고, 완성된 Go server/WAM 구현은 이 저장소에서 확인하세요. SDK Quickstart도 이 튜토리얼을 실행 가능한 Go 예제로 연결합니다.