{"page":1,"pageSize":20,"count":170,"next":"/api-public/v3/ipd-thor/api/v1/workspaces/15/posts?categoriesSlug=tech&page=2&size=20","previous":null,"results":[{"id":39877,"updatedTime":"2025-08-28T04:11:52+09:00","createdTime":"2025-08-25T12:32:21+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"신용대출 찾기 서비스 제휴사 Mock 서버 개발기 #2","subtitle":"대출 연동 테스트의 안정성과 효율성을 극대화하는 mock 서버 개발기의 후속 내용을 공유합니다.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/illusts-content/0613_techthumb.png","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts-content/0613_techthumb.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"credit-loan-partner-mock-server-2","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-08-27T14:25:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":39877,"title":null,"description":"안녕하세요, 토스 Financial Marketplace Platform Team Server Developer 류경린입니다.이번 글에서는 지난 아티클에서 소개한 제휴사 mock 서버를 더 효과적으로 활용하기 위해 어떤 고민을 했는지 를 소개하고자 해요. 이를 위해 통합 테스트 작성 과...","urlSlug":"credit-loan-partner-mock-server-2","primaryKeyword":{"id":52859,"content":"모의서버","wordType":"SEO_KEYWORD"},"relatedKeywords":[],"tags":[{"id":41784,"content":"Server","wordType":"TAG"}]},"openGraph":{"title":"신용대출 찾기 서비스 제휴사 mock 서버 개발기 #2","description":"안녕하세요, 토스 Financial Marketplace Platform Team Server Developer 류경린입니다.이번 글에서는 지난 아티클에서 소개한 제휴사 mock 서버를 더 효과적으로 활용하기 위해 어떤 고민을 했는지 를 소개하고자 해요. 이를 위해 통합 테스트 작성 과...","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/illusts-content/0613_techthumb.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2565,"name":"류경린","slug":null,"shortDescription":null,"description":null,"imageUrl":null,"url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":2,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, 토스 Financial Marketplace Platform Team Server Developer 류경린입니다.\n이번 글에서는 지난 아티클에서 소개한 제휴사 Mock 서버를 더 효과적으로 활용하기 위해 어떤 고민을 했는지 를 소개하고자 해요. 이를 위해 통합 테스트 작성 과정과, 유지보수의 어려움을 줄이기 ","fullDescription":"안녕하세요, 토스 Financial Marketplace Platform Team Server Developer 류경린입니다.\n이번 글에서는 지난 아티클에서 소개한 제휴사 Mock 서버를 더 효과적으로 활용하기 위해 어떤 고민을 했는지 를 소개하고자 해요. 이를 위해 통합 테스트 작성 과정과, 유지보수의 어려움을 줄이기 위해 어떤 접근 방식을 시도했는지 경험을 나눠보려 합니다.\n\n통합 테스트\n현재 신용대출 찾기 서비스의 경우, E2E(End-to-End) 테스트가 자동화 되어 있지 않습니다.\n이로 인해 Mock 서버를 만들었지만 제휴사 코드를 변경할 때마다 사람이 직접 테스트를 해야하고, 이는 곧 테스트를 누락할 수 있음을 의미해요. 완전한 E2E 테스트를 도입하는 것이 가장 이상적이지만, 팀 상황 상 당장 적용하기는 어려웠습니다.\n이에 Docker 환경에서 Mock 서버를 띄우고 통합 테스트를 Github Action에서 수행하는 방식으로 문제를 해결하고자 했어요.\n\nMock 서버 띄우기\n토스는 Spring Cloud Config 를 활용해 프로퍼티를 주입하고 있고, Local, Alpha, Staging, Live 4개의 환경을 운영하고 있습니다. (제휴사 Mock 서버의 경우 Local, Alpha 환경만을 운영하고 있어요.)\n내부 라이브러리에서 참조하는 프로퍼티들이 Spring Cloud Config 값을 의존하고 있기 때문에, Mock 서버를 띄울 때 Local, Alpha가 아닌 제 3의 Profile을 사용하는 것에는 어려움이 있었습니다.\n\n이런 어려움 때문에 2개의 환경 중 하나를 희생해야했고, Alpha 환경은 E2E 테스트를 진행했어야 했기에 Local 환경을 포기하고자 했습니다. 하지만 새로운 서비스들이 Mock 서버 연동을 해야하는 상황에서 Local 환경을 사용할 수 없게 되는 것은, 앞으로의 생산성에 영향을 크게 미치는 문제였고 이 방법을 채택할 수 없었습니다.\n\nSpring Cloud Config를 활용하면서, 내가 원하는 값에 대해서만 Mock 서버 기반 통합테스트 환경에서 오버라이드 할 수 있는 방법이 없을까를 고민하다 Multi Profile 을 사용하면 문제를 해결할 수 있음이 떠올랐습니다.\nMock 서버 기반 통합테스트를 위한 mockServerTest라는 Profile을 정의하고, 내부적으로 Docker 환경에서 사용할 인프라 정보를 오버라이드 함으로써 문제를 해결할 수 있었습니다.\n\napplication-find-loan-mockServerTest.properties\nmockServerTest 프로파일에 docker 환경에서 사용할 인프라 환경을 구성합니다.\nspring.datasource.find-loan.jdbc-url=jdbc:mysql://mysql:3306/{database}\n...\n\n# find-loan\ntoss.servers.find-loan.domain=http://host.docker.internal:8080\napplication-mockServerTest.properties\napplication-find-loan-mockServerTest.properties 를 config 에 병합함으로써, docker 환경에 맞는 인프라 가 spring config 에 설정됩니다.\nspring.config.import+=classpath:application-find-loan-mockServerTest.properties\n\nJPA 설정\n지난 아티클에서 말씀드렸듯이, Mock 서버는 각 서비스가 모듈로 존재하는 멀티 모듈 프로젝트 구조입니다. 이때 서비스 별로 패키지 구조가 정의되다 보니, 동일한 패키지 경로가 겹칠 수 있는 문제가 있었습니다.\n이로 인해 패키지 구조가 같은 Entity들이 각각의 DataSource에 중복으로 추가되는 문제가 발생했어요.\n\n예를 들어 org.test.entity라는 패키지를 사용하는 test-a 모듈과 test-b 모듈이 있을 경우, test-a의 DataSource에 entity-a와 entity-b가 모두 생성되고, test-b의 DataSource에도 동일한 entity-a와 entity-b가 중복으로 생성됩니다.\n이렇게 불필요한 테이블이 생성되는 문제를 막기 위해 ddl-auto 설정을 끄고, init.sql을 사용해 Spring Application이 실행될 때 필요한 테이블만 생성되도록 처리했습니다.\n# JPA ddl-auto 비활성\nspring.jpa.generate-ddl=false\nspring.jpa.hibernate.ddl-auto=none\n\n# mockServerTest 에서만 init 을 활성화\nspring.sql.init.mode=always\nspring.sql.init.schema-locations=classpath:init_base_tables.sql,classpath:init_find_loan_api_tables.sql,classpath:init_find_loan_api_data.sql\n\n통합테스트\n테스트는 원칙상 테스트 간 순서 의존성을 가지면 안됩니다.\n하지만 신용대출 찾기 서비스의 경우, 퍼널 별로 통합 테스트를 하기 위해서는 반드시 ‘가심사 신청’ 퍼널을 진행해야 해요. 이 경우, 하나의 퍼널을 테스트하기 위해 N분씩 Action의 수행 시간이 길어지는 문제가 있습니다.\n테스트 실행 시간이 길어지는 문제 때문에 ‘테스트는 독립적이어야 한다’ 라는 대명제를 깨고, 가심사는 통합 테스트에서 1회만 돌리고, 해당 원장 데이터를 사용해 각각의 퍼널에 대해 테스트를 하는 형태로 진행했습니다.\n\n단일 클래스 내에서는 @Order 어노테이션을 사용해 순서를 지정할 수 있지만, 클래스 간의 테스트 순서를 보장할 수는 없었습니다. (모든 퍼널에 대해 단일 클래스 내에서 @Order를 사용하는 방식은 여러 퍼널에 대한 테스트 관심사가 하나의 파일 내에 존재하여 지양하고자 했습니다.)\n\njunit의 @Suite를 사용하는 경우, 클래스 간의 테스트 순서를 보장할 수 있어 해당 방식을 채택했습니다.\na test suite is a collection of tests grouped together and run as a single unit (reference)\n@Suite\n@SelectClasses(value = [수기입력가심사::class, 대출실행::class, 대출거절::class])\nclass AllFunnelsSuite\n\n아래 의존성을 추가하면 @Suite를 사용할 수 있습니다.\nval junitJupiterVersion = \"5.10.0\"\nval junitPlatformVersion = \"1.10.0\"\n\ntestImplementation(\"org.junit.jupiter:junit-jupiter:$junitJupiterVersion\")\ntestImplementation(\"org.junit.jupiter:junit-jupiter-api:$junitJupiterVersion\")\ntestImplementation(\"org.junit.jupiter:junit-jupiter-engine:$junitJupiterVersion\")\n\ntestImplementation(\"org.junit.platform:junit-platform-suite-api:$junitPlatformVersion\")\ntestImplementation(\"org.junit.platform:junit-platform-suite-engine:$junitPlatformVersion\")\ntestImplementation(\"org.junit.platform:junit-platform-commons:$junitPlatformVersion\")\ntestImplementation(\"org.junit.platform:junit-platform-engine:$junitPlatformVersion\")\ntestRuntimeOnly(\"org.junit.platform:junit-platform-launcher:$junitPlatformVersion\")\n\nGithub Action을 사용한 통합 테스트\nGithub Action을 사용해 Mock 서버를 활용한 통합 테스트를 실행하고, 테스트 결과에 대한 가시성을 높이기 위해 아래 2개의 정책을 정의했습니다.\nfeature branch → develop으로 merge 할 때, 테스트가 실패한다면 PR 작성자에게 테스트가 실패했음을 알려준다.\n\ndevelop → master로 merge 할 때, 테스트 성공 여부 및 제휴사 코드 변경 여부를 배포 파이프 라인에서 알려준다.\n\nMock 서버 데이터 자동 마이그레이션\nMock 서버를 안정적으로 운영하려면 E2E 테스트와 통합 테스트에 필요한 Mock 데이터를 꾸준히 유지보수 해야 합니다. 하지만 제휴사 코드를 수정할 때마다 데이터를 직접 마이그레이션하고 관리하는 일은 번거롭고 누락되기 쉽습니다.\n이런 유지보수 비용을 최소화하기 위해, 제휴사 코드에 변경이 발생하면 E2E 테스트용 데이터 마이그레이션과 통합 테스트용 init 쿼리를 자동으로 수정해 PR(Pull Request)을 생성하도록 했습니다.\n\n제휴사 코드 변경 감지\n먼저 GitHub Actions에서 git diff를 사용해 특정 패키지 내 파일에 변경이 있었는지 확인합니다.\n- name: Check for partner code changes\n id: check_partner\n run: |\n mkdir -p output\n if git diff-tree --no-commit-id --name-only -r HEAD^ HEAD | grep '.*/findloan/partner/.*Dto.*'; then\n # TODO(제휴사 DTO 명세 추출)\n # TODO(제휴사 DTO 명세 기반 자동 PR 생성)\n fi\n\n제휴사 DTO 명세 추출\n데이터 마이그레이션을 위해서는 Mock 서버가 각 서비스의 제휴사 DTO 명세를 알고 있어야 합니다.\n각 서비스에서는 Kotlin Reflections를 사용해 특정 패키지 내 클래스를 스캔하고, 스키마 추출 대상임을 표시하기 위해 @GenerateSchema라는 커스텀 어노테이션을 사용합니다.\nval reflections = Reflections(packageName)\nreflections\n .getTypesAnnotatedWith(GenerateSchema::class.java)\n .map { it.kotlin }\n .map { clazz ->\n val schema = schemaGen.generateSchema(clazz.java)\n val jsonSchema = mapper.writerWithDefaultPrettyPrinter().writeValueAsString(schema)\n ...\n }\n스키마 추출 방법은 여러 가지가 있지만, 저희 팀은 다음 이유로 Jackson 라이브러리의 JSON Schema를 선택했습니다.\n여러 서비스에서 동일한 포맷으로 스키마를 공유할 수 있고, @JsonPropertyDescription 어노테이션 등을 활용해 프로퍼티에 설명이나 예약어를 쉽게 추가할 수 있음\n별도의 추가 개발 없이 라이브러리만으로 스키마를 손쉽게 추출할 수 있음\n아래는 실제로 추출된 JSON Schema 예시입니다.\n{\n \"type\" : \"object\",\n \"id\" : \"urn:jsonschema:com:test:service:common:TestBank:TestBankDto:PreScreeningResponse\",\n \"properties\" : {\n \"code\" : {\n\t \"type\" : \"string\"\n },\n \"data\" : {\n\t \"type\" : \"any\"\n }\n }\n}\n이렇게 추출한 JSON Schema는 S3에 업로드하여 이후 프로세스에서 활용됩니다.\n\nJSON Schema 를 활용한 json 샘플 데이터 생성\nS3에서 JSON Schema를 다운로드한 뒤 이를 기반으로 각 제휴사의 퍼널별 샘플 데이터를 생성합니다.\nJSON Schema의 id는 패키지명:클래스명으로 구성되어 있어 어떤 제휴사/퍼널에 대한 스키마인지 파악할 수 있습니다.\nproperties는 중첩된 형태로 key = 프로퍼티명, value = 타입으로 구성되어 있으므로 이를 역으로 분석해 JsonNode를 재구성합니다.\nval factory = JsonNodeFactory.instance\n\nfun generateExample(node: JsonNode): JsonNode {\n\t\tval json = factory.objectNode()\n\t\t\n\t\tprops.fields().forEach { (key, prop) ->\n\t\t\t\tval desc = prop.get(\"description\")?.asText()\n\t\t val type = prop.get(\"type\")?.asText()\n\t\t}\n\t\t\n\t\tif (type == \"object\" || type == \"array\") {\n ...\n val example = generateExample(childNode)\n ...\n example.response?.fields()?.forEach { (k, v) -> json.set(k, v) }\n\n } else {\n\t\t // 샘플 데이터 주입\n json.set(key, schemaToSample(prop))\n }\n}\n이후 기존에 정의되어 있던 JSON 값과 새로 생성된 JsonNode 를 병합해, 기존에 있던 프로퍼티는 그대로 두고 새로 추가된 프로퍼티만 샘플 데이터를 채워넣도록 합니다.\n기존 데이터가 중요한 경우를 고려해 기존 값에 우선순위를 둔 것이 핵심입니다.\n\n데이터 마이그레이션\n생성한 샘플 데이터를 사용해 E2E 테스트용 데이터를 마이그레이션하고, 통합 테스트에서 사용할 init.sql 파일을 업데이트합니다.\nxxx.forEach { (type, status) ->\n val existed = partnerResponses.firstOrNull { it.type == type && it.status == status } ?: return@forEach\n val newJsonLayout = jsonLayout?.let { JsonMerger.merge(it, existed.jsonLayout) }\n val newResponse = response?.let { JsonMerger.merge(it, existed.response) }\n\n existed.response = newResponse\n existed.jsonLayout = newJsonLayout\n}\ninit.sql은 마이그레이션된 데이터에 맞게 자동으로 생성됩니다.\nfun migrate(localPath: File) {\n val file = getFile(localPath)\n val query = generate()\n file.writeText(query)\n}\n\nprivate fun generate() {\n\t\tval queryBuilder = StringBuilder()\n\t\t...\n\t\t\n\t\treturn queryBuilder.toString()\n}\n\nPull Request 자동 생성\n마지막으로 자동화된 데이터 마이그레이션 결과를 자동으로 PR로 올리는 기능을 구현했습니다. 이를 위해 JGit 라이브러리를 사용해 애플리케이션 내에서 Git 기능을 실행합니다.\n토스는 GitHub Enterprise 환경을 사용하고 있기 때문에 GitHub App을 통해 토큰을 발급받고, 이를 이용해 인증된 Git 명령을 실행합니다.\n\n토큰 발급은 아래 순서를 따라주면 됩니다.\n1️⃣ GitHub Enterprise App을 추가하고 Private Secret Key를 발급\n2️⃣ Secret Key를 PKCS#1 → PKCS#8로 변환한 뒤 RSA Private Key 발급\nopenssl pkcs8 -topk8 -inform PEM -outform PEM -in {{origin secret}}.pem -out {{new secret}}.pem -nocrypt 을 활용해 포맷 변환\n아래 코드를 활용해 RSA Private Key 발급\nprivate fun readPrivateKey(pem: String): RSAPrivateKey {\n val base64Content = pem\n .replace(\"-----BEGIN PRIVATE KEY-----\", \"\")\n .replace(\"-----END PRIVATE KEY-----\", \"\")\n .replace(\"\\\\s\".toRegex(), \"\")\n\n val decoded = Base64.getDecoder().decode(base64Content)\n\n val kf = KeyFactory.getInstance(\"RSA\")\n val spec = PKCS8EncodedKeySpec(decoded)\n return kf.generatePrivate(spec) as RSAPrivateKey\n}\n3️⃣ JWT 발급\nprivate fun createJsonWebToken(): String {\n val algorithm = Algorithm.RSA256(null, readPrivateKey(secret))\n val now = Instant.now()\n return JWT.create()\n .withIssuer(APP_ID)\n .withIssuedAt(Date.from(now))\n .withExpiresAt(Date.from(now.plusSeconds(300)))\n .sign(algorithm)\n}\n4️⃣ JWT를 사용해 Installation Token 발급\nwebClient.post()\n .uri(\"/api/v3/app/installations/$installationId/access_tokens\")\n .addHeaders(mapOf(\"Authorization\" to \"Bearer $jwt\"))\n .retrieve()\n .bodyToMono>() // JSON map 으로 받음\n .block()\n\nreturn response[\"token\"] as String\n\n전체 플로우\n전체 플로우를 코드 레벨로 나타내면 아래와 같습니다.\nfun generate() {\n val files = downloader.downloads(service)\n val localPath = Files.createTempDirectory(\"fmd-mock-server\").toFile()\n\n // json schema 를 사용해 E2E 환경의 테스트 데이터 변경을 위한 엔티티 마이그레이션 을 진행한다.\n val jsonMigrateHandler = jsonMigrateHandlers.first { it.canHandle(service) }\n val isChanged = jsonMigrateHandler.migrate(files)\n\n try {\n if (isChanged) {\n gitService.clone(localPath)\n // 지라 티켓을 발급한다.\n val issueKey = {\n\t\t\t ...\n\t\t jiraService.createIssue()\n }\n\n val branch = \"feature/$issueKey\"\n gitService.checkout(branch)\n // entity 를 기반으로 통합테스트 를 위한 init.sql 파일 마이그레이션 을 진행한다.\n val mockServerQueryMigrateHandler = mockServerQueryMigrateHandlers.first { it.canHandle(service) }\n mockServerQueryMigrateHandler.migrate(localPath)\n\n gitService.push(branch, \"[$issueKey] [${service.description}] migrate mock data\")\n // PR 이 이미 올라가있는 경우, PR 생성 요청을 하지 않는다.\n gitService.pullRequest(\"[$issueKey] [${service.description}] mock data migration PR\", branch, pullRequestLink)\n } else {\n logger.info { \"변경사항이 존재하지 않습니다. $service: ${service.name}, pullRequestLink: $pullRequestLink, assignee: $assignee\" }\n }\n } finally {\n gitService.clear()\n localPath.deleteRecursively()\n files.forEach { it.deleteRecursively() }\n }\n}\n\n\n이 과정을 통해 제휴사 DTO에 변경이 발생하면 데이터 마이그레이션부터 init.sql 갱신, PR 생성까지 자동으로 처리 됩니다. 이로써 사람이 직접 테스트 데이터를 관리해야 하는 부담을 줄이고, 누락 없이 안정적으로 mock 서버 데이터를 유지할 수 있습니다.\n\n\n\n\n\n\n마치며\n이번 글에서는 신용대출 서비스에서 Mock 서버를 어떻게 통합 테스트와 연결하고, 데이터 마이그레이션을 자동화해 운영 비용을 줄였는지에 대한 내부 고민과 시도들을 공유했습니다.\n물론 이상적인 시나리오는 E2E 테스트가 모든 케이스를 완전히 보장해주는 것이지만, 현실적인 팀의 상황과 인프라 제약 속에서 적절한 우회와 자동화가 필요했습니다. 특히 multi profile 전략, Jackson 기반 JSON Schema 추출, JGit과 Github App을 활용한 PR 자동화는 작은 노력이지만 유지보수 비용을 크게 줄여준 중요한 선택지였습니다. 이런 과정들은 서비스 규모가 커지고, 협업해야 할 대상이 많아질수록 더 큰 효과를 발휘합니다.\n앞으로도 mock 서버를 통해 실제 제휴사 환경과 최대한 유사한 테스트 환경을 유지하면서, 개발자가 신뢰할 수 있는 데이터와 테스트 구조를 계속 개선해 나갈 예정입니다. 이 글이 비슷한 고민을 하고 계신 분들께 조금이나마 도움이 되길 바랍니다.\n읽어주셔서 감사합니다.\n\n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":932},{"id":38743,"updatedTime":"2025-08-28T03:32:24+09:00","createdTime":"2025-07-21T14:47:39+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""},{"name":"접근성 업무일지","id":1935,"slug":"universal_design","parentId":null,"iconUrl":"https://static.toss.im/illusts-content/0704-tech-accessibility-series-thumb.png"}],"series":null,"seriesSlug":null,"title":"귀로 듣는 챗봇의 탄생 | 접근성 업무일지 #3","subtitle":"스크린리더 사용자에게도 챗봇 흐름이 자연스럽게 느껴지게 하기 위해 고민한 4가지 포인트를 알려드려요.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts-content/0704-tech-accessibility-cover.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"38743","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-08-13T15:16:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":38743,"title":null,"description":"안녕하세요! 저는 토스코어에서 CX Product Team 소속으로 프론트엔드 개발을 하고 있는 손연지라고 합니다. 스크린리더 사용자에게도 챗봇 흐름이 자연스럽게 느껴지게 하기 위해 고민한 4가지 포인트를 알려드려요.","urlSlug":"38743","primaryKeyword":{"id":53115,"content":"토스 접근성","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":37472,"content":"토스","wordType":"SEO_KEYWORD"},{"id":49395,"content":"접근성","wordType":"SEO_KEYWORD"},{"id":53123,"content":"토스 접근성팀","wordType":"SEO_KEYWORD"},{"id":55061,"content":"토스 고객센터","wordType":"SEO_KEYWORD"}],"tags":[]},"openGraph":{"title":"눈 대신 귀로 느낄 수 있는 챗봇 흐름 만들기 | 접근성 업무일지 #3","description":"안녕하세요! 저는 토스코어에서 CX Product Team 소속으로 프론트엔드 개발을 하고 있는 손연지라고 합니다. 스크린리더 사용자에게도 챗봇 흐름이 자연스럽게 느껴지게 하기 위해 고민한 4가지 포인트를 알려드려요.","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/illusts-content/0704-tech-accessibility-cover.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2609,"name":"손연지","slug":null,"shortDescription":null,"description":null,"imageUrl":null,"url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요! 저는 토스코어에서 CX Product Team 소속으로 프론트엔드 개발을 하고 있는 손연지라고 합니다. 지금까지는 상담 대시보드, 내부 상담 어드민, STT 어드민 같은 CX 인터널 제품들을 주로 개발해왔고, 최근에는 대고객 제품인 고객센터 챗봇 서비스를 맡아 개발하고 있어요.\n\n토스 고객센터 챗봇에서 상위 ","fullDescription":"안녕하세요! 저는 토스코어에서 CX Product Team 소속으로 프론트엔드 개발을 하고 있는 손연지라고 합니다. 지금까지는 상담 대시보드, 내부 상담 어드민, STT 어드민 같은 CX 인터널 제품들을 주로 개발해왔고, 최근에는 대고객 제품인 고객센터 챗봇 서비스를 맡아 개발하고 있어요.\n\n토스 고객센터 챗봇에서 상위 서비스를 선택하면, 그에 맞는 하위 선택 화면으로 전환되면서 여러 개의 버튼이 나타나요. 예를 들어 송금에 대해 문의하면, “송금 한도가 궁금해요”, “송금 한도를 변경하고 싶어요” 같은 버튼들이 새롭게 나타나죠. 어느 날 접근성 관련 피드백을 하나 받았어요. 새로운 메시지가 떠도, 스크린리더 사용자 입장에서는 화면이 바뀌었다는 걸 전혀 인지할 수 없었다는 거예요.\n\n실제로 화면이 바뀌었는데도 초점은 그대로 이전 위치에 머물러 있으니, 스크린리더 사용자 입장에서는 새로운 흐름이 시작됐다는 걸 전혀 알 수 없었던 거예요. 이 문제를 해결하기 위해, 눈으로 보면 당연하게 느껴지는 화면의 흐름을, 보지 않아도 자연스럽게 따라갈 수 있는 설계를 고민하게 되었어요.\n\n\n\n 개선 1 — 시각적 UI의 흐름을 초점 이동에 반영하기\n\n우선 스크린리더를 쓰지 않는 사용자가 챗봇을 사용할 때의 흐름을 떠올렸어요. 보통은 상위 항목을 누르면 새로운 메시지가 뜨고, 그 아래에 하위 선택 버튼들이 등장하죠. 자연스럽게 시선을 따라가며 다음 행동으로 넘어가게 돼요.\n\n스크린리더 사용자에게는 이 시선의 흐름을 초점 이동이 대신 해줘야 해요. 그래서 화면이 바뀌었을 때는 초점도 함께 이동해줘야, 흐름이 끊기지 않을 수 있어요.\n챗봇의 UI는 위 영상에서처럼 안내 메시지와 그에 따른 선택 버튼으로 구성되어있어요. 사용자가 버튼을 누르면 선택한 값이 ‘보낸 메시지’로 표시되는데, 이때 초점을 곧바로 보낸 메시지로 이동시켜야 대화 흐름이 자연스럽게 이어져요.\n\n\n개선 2 — 초점 이동 타이밍을 정교하게 조정하기\n\n초점만 잘 옮겨주면 해결된다고 생각했는데, 초점이 언제, 어떻게 이동하느냐가 훨씬 더 중요했어요.\n\n개선 과정에서 초점을 자동으로 옮기기 위해 target.focus()를 사용했더니, 브라우저가 해당 요소로 즉시 점프(scroll)해버리면서 기존에 잘 작동하던 챗봇의 부드러운 자동 스크롤scrollIntoView({ behavior: 'smooth' }) 이 무시되는 문제가 생겼어요. focus()가 강제로 즉시 스크롤을 발생시키면서, 스크롤이 ‘훅’ 튀는 느낌이 되어버린 거죠.\n\n그래서 아래와 같이 흐름을 정교하게 나눠서 구현했어요:\n\n먼저 메시지 박스를 scrollIntoView({ behavior: 'smooth' })로 부드럽게 스크롤시키고,\n\n스크롤이 어느 정도 끝났을 타이밍(약 1초 후)에\ntarget.focus({ preventScroll: true })를 호출해서 초점을 이동시켰어요.\n\npreventScroll: true 옵션 덕분에 초점 이동이 스크롤 위치를 다시 덮지 않게 만들 수 있었고요.\n\ntarget.scrollIntoView({ behavior: 'smooth' });\n\nsetTimeout(() => {\n target.focus({ preventScroll: true });\n}, 1000);\n\n\n이렇게 흐름을 나눠서 처리하니, 시각적으로도 자연스럽고 초점도 정확한 위치에 도달했어요. 스크린리더 역시 그 타이밍에 맞춰 끊김 없이 안내를 이어갈 수 있었고요.\n결과적으로 사용자는 부드러운 스크롤과 또렷한 초점 이동 흐름을 함께 경험할 수 있었어요.\n\n개선 3 — 버튼 존재 알려주는 안내 추가하기\n\n\n\n*음성안내가 있으니 꼭 소리를 켜고 재생해주세요.\n\n텍스트 메시지 아래에 버튼이 있는 경우, 초점이 버튼까지 도달하지 않으면 버튼이 있는지조차 모른 채 지나치게 돼요. 그래서 메시지가 끝난 뒤, 스크린리더 전용으로 “아래 메뉴 버튼을 선택해 주세요”라는 안내를 추가했어요.\n\n아래 메뉴 버튼을 선택해 주세요.\n\n이 메시지는 시각적으로는 보이지 않지만, 스크린리더 사용자는 들을 수 있어요. “아, 이제 선택할 수 있는 버튼이 있구나” 하고 흐름을 놓치지 않을 수 있죠.\n시각적 디자인은 그대로 유지하면서도, 음성 흐름상 필요한 안내를 덧붙여주는 방식으로 흐름을 보완할 수 있었어요. \n\n\n개선 4 — 메시지 상황에 대한 청각 피드백 주기\n\n*음성안내가 있으니 꼭 소리를 켜고 재생해주세요.\n\n상담원이 메시지를 입력 중이거나, 메시지를 보냈을 때, 일반 사용자는 화면의 변화나 타이핑 애니메이션 등을 통해 이를 쉽게 인식할 수 있어요. 하지만 스크린리더 사용자에겐 이 모든 맥락이 공백이에요. 그래서 이런 시각적 정보를 음성으로 안내하려고 했죠.\n상담원이 입력 중일 때는 aria-live=\"polite\" 속성을 활용해 “상담원이 메시지를 입력 중입니다”라는 음성을 안내했어요. 메시지를 보낼 때 / 받을 때 시점에 각각 효과음을 재생해 상황에 대한 피드백을 주려고 했어요.\n스크린리더 음성이 겹쳐도 효과음은 별도로 울리기 때문에, 메시지를 못 들었더라도 “무언가가 방금 발생했구나”를 인지할 수 있어요. 메시지 효과음은 사실 우리 모두에게 익숙한 경험이에요. 눈으로 확인한 정보에 소리로 피드백이 더해지면, 그 경험은 더 선명하게 느껴져요. 이 개선은 시각장애인을 위한 대응이자, 모든 사용자에게 익숙하고 친절한 사용성을 제공하는 방식이기도 했어요.\n\n\n\n개선 이후\n프론트엔드 개발자로서 이번 작업은 단순한 기능 구현이 아니라, 사용자의 인지 흐름을 설계한 경험이었어요. 직접 스크린리더를 켜고 눈을 감고 탐색해보며 “내가 과연 이 흐름을 이해할 수 있을까?” 를 계속 되묻는 시간이었죠.\n접근성은 특정 상황에 놓인 사용자만을 위한 기능이 아니었어요. 오히려 모든 사용자에게 더 명확하고, 더 친절한 흐름을 설계하는 일이라는 걸 깊이 느낄 수 있었어요.\n특히 메시지 수신/발신 효과음 같은 기능은 누구에게나 익숙한 대화의 리듬을 더 또렷하게 만들어주는 요소가 될 수 있죠. 소리 피드백이 더해지면 사용자 입장에서 흐름은 더 선명해지니까요.\n이번이 처음 해본 접근성 개선 작업이었지만, 앞으로 개발하는 모든 화면에서 반드시 함께 고려해야 할 하나의 기준이 생긴 것 같아요.\n앞으로는 이 흐름을 팀 내 공통 패턴으로 확장해보고 싶어요. 초점 이동이나 타이밍 제어 같은 것들은 재사용 가능한 유틸로 만들면 다른 화면에도 쉽게 적용할 수 있을 거예요.\n접근성은 소수만을 위한 고려가 아니라, 모든 사용자에게 더 나은 흐름을 제공하는 방법이라는 걸 배웠습니다. “눈을 감고도 안심하고 사용할 수 있는 서비스”를 위해 앞으로도 계속 고민해볼게요.\n\n\n\n\n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":3192},{"id":39567,"updatedTime":"2025-08-28T03:01:01+09:00","createdTime":"2025-08-12T20:30:47+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""},{"name":"접근성 업무일지","id":1935,"slug":"universal_design","parentId":null,"iconUrl":"https://static.toss.im/illusts-content/0704-tech-accessibility-series-thumb.png"}],"series":null,"seriesSlug":null,"title":"토스의 접근성 문서 A11y Fundamentals 을 소개합니다 (오픈 기념 이벤트 ~9/10)","subtitle":"'접근성은 어려운 것' 이라고 느끼는 분들을 위해 실무에서 바로 적용할 수 있는 접근성의 핵심 개념과 실수하기 쉬운 패턴을 알려주는 문서, A11y Fundamentals 을 소개합니다.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/photos/Ally.jpg","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"A11y_Fundamentals","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-08-13T13:12:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":39567,"title":null,"description":"'접근성은 어려운 것' 이라고 느끼는 분들을 위해 실무에서 바로 적용할 수 있는 접근성의 핵심 개념과 실수하기 쉬운 패턴을 알려주는 문서, A11y Fundamentals 을 소개합니다.","urlSlug":"A11y_Fundamentals","primaryKeyword":{"id":53115,"content":"토스 접근성","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":37472,"content":"토스","wordType":"SEO_KEYWORD"},{"id":49395,"content":"접근성","wordType":"SEO_KEYWORD"},{"id":53123,"content":"토스 접근성팀","wordType":"SEO_KEYWORD"}],"tags":[]},"openGraph":{"title":"토스의 접근성 문서 A11y Fundamentals 을 소개합니다 (오픈 기념 이벤트 ~9/10)","description":"'접근성은 어려운 것' 이라고 느끼는 분들을 위해 실무에서 바로 적용할 수 있는 접근성의 핵심 개념과 실수하기 쉬운 패턴을 알려주는 문서, A11y Fundamentals 을 소개합니다.","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/photos/Ally.jpg","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2385,"name":"강민우","slug":"minwoo-kang","shortDescription":"토스 Frontend Developer","description":".","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":2,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"A11y Fundamentals 이란?\n토스는 ‘누구나 금융을 쉽게’ 사용할 수 있는 세상을 꿈꿔요. 그래서 제품을 만들 때도, 문서를 쓸 때도, 접근성을 고민합니다. 접근성(Accessibility, 줄여서 A11y)은 모든 사용자가 더 쉽고 편리하게 웹을 사용할 수 있도록 돕는 기본 원칙이에요. \n개발자분들과 이야기하","fullDescription":"A11y Fundamentals 이란?\n토스는 ‘누구나 금융을 쉽게’ 사용할 수 있는 세상을 꿈꿔요. 그래서 제품을 만들 때도, 문서를 쓸 때도, 접근성을 고민합니다. 접근성(Accessibility, 줄여서 A11y)은 모든 사용자가 더 쉽고 편리하게 웹을 사용할 수 있도록 돕는 기본 원칙이에요. \n개발자분들과 이야기하다 보면, 접근성이 중요하다는 건 알지만 어떻게 시작해야 할지 모르겠다는 이야기를 많이 들어요. 그래서 토스는 실제 개발 과정에서 자주 부딪히는 실수와 핵심 개념을 정리한 접근성 문서 A11y Fundamentals 을 오픈했어요.\n'접근성은 어려운 것' 이라고 느끼는 분들을 위해 실무에서 바로 적용할 수 있는 접근성의 핵심 개념과 실수하기 쉬운 패턴을 알려줘요. 버튼 안에 버튼을 넣으면 왜 안 되는지, 태그 안에 );\nexpect(screen.getByRole('button', { name: '저장' })).toBeInTheDocument();\n\n같은 이름을 가진 여러 요소가 있을 때도, 상위 요소의 접근성 레이블을 활용하면 구분도 쉽고, 사용자가 쉽게 선택할 수 있어요.\n\n// 같은 이름의 요소를 상위 접근성 역할 설정을 통해 특정 짓기\nrender(\n

\n 사과\n \n
\n 복숭아\n \n

\n);\nconst 복숭아 = screen.getByRole('listitem', { name: '복숭아' });\nconst 복숭아저장버튼 = getByRole(복숭아, 'button', { name: '저장' })\nexpect(복숭아저장버튼).toBeInTheDocument();\n\n반면, querySelector를 사용해서 요소를 선택하면 마크업 구조가 조금만 바뀌어도 테스트가 쉽게 깨질 수 있어요. ByTestId 는 테스트를 위해 별도의 속성을 추가해야 하고, 이 값이 서비스 코드에 남는다는 단점이 있어요. 하지만 ByRole을 사용하면 실제 사용자와 동일한 방식으로 요소를 찾을 수 있고, 유일한 역할을 가진 요소를 쉽게 특정할 수 있어요. 이는 접근성을 잘 지킨 마크업 구조에서만 가능한 일이에요.\n\n// querySelector를 사용하는 경우 (마크업 구조가 바뀌면 깨질 수 있어요)\nexpect(document.querySelector('ul > li:nth-child(2) > button')).toBeInTheDocument();\n\n// getByTestId를 사용하는 경우 (테스트용 속성이 서비스 코드에 남아요)\nrender();\nexpect(screen.getByTestId('save-btn')).toBeInTheDocument();\n즉, 접근성은 사용자 모두를 위한 것이면서, 개발자에게도 더 견고하고 유지보수하기 쉬운 코드를 만들 수 있게 도와줘요.\n\n\n\n주요 원칙\n웹 콘텐츠 접근성을 높이기 위해 네 가지 핵심 원칙과 각 원칙을 지킬 수 있는 구체적인 방법을 제안볼 수 있어요. 자세한 내용은 눌러서 확인해보세요.\n\n1. 구조를 명확하게 만들기\n버튼 안에 버튼 넣지 않기\n테이블 행에 직접 onClick 붙이지 않기\n\n2. 의미를 정확히 전달하기\n인터렉티브 요소에 이름 붙이기\n같은 이름의 요소에는 설명 추가하기\n\n3. 예상 가능한 동작 만들기\n버튼의 역할과 동작이 일치하게 만들기\n입력 요소는 으로 감싸기\n\n4. 시각 정보 보완하기\n이미지와 아이콘에 적절한 대체 텍스트 제공하기\n\n\n\n\n\n🔊 토스 송금 스크린리더 체험 이벤트 ( ~9/10 )\nA11y Fundamentals 문서 오픈을 기념해, 특별한 체험 이벤트도 함께 준비했어요.\n스크린리더 환경에서 소리만으로 송금하기, 직접 경험해보세요.\n\n참여 방법\n1.[체험하기 페이지]에서 스크린리더 환경으로 송금 서비스를 사용해보세요.\n2.체험 완료 스크린샷을 깃허브 페이지에 댓글로 남겨주세요.\n3.참여해주신 분 중 추첨을 통해 선물을 드립니다!\n🎁 당첨자분에게는 9월 10일에 GitHub에 등록된 이메일로 개별 안내드려요.\n관련 메시지를 받는 경우 반드시 정식 계정 여부를 확인 부탁드려요. (본 이벤트는 카드 등록 및 결제 관련 정보 등을 절대로 요구하지 않아요.)\n당첨 안내 시 사용되는 이메일은 안내 목적으로만 이용되며, 별도로 저장하지 않아요.\n\n접근성이 왜 중요한지, 그리고 스크린리더 환경이 어떤지, 직접 체험해보면 훨씬 더 깊이 이해할 수 있어요. 이번 이벤트가 그런 작은 계기가 되어주길 바랍니다.\n\n\n\n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":7790},{"id":38205,"updatedTime":"2025-08-28T04:04:21+09:00","createdTime":"2025-07-04T10:59:13+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"슬기로운 토스뱅크 개발 인턴 생활 ","subtitle":"토스뱅크에서 3개월 동안 개발 인턴으로 근무하며 기획·개발·발표까지 진행해본 경험을 공유할게요.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/photos/toss-bank-interns.jpg","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"toss-bank-interns","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-07-14T12:50:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":38205,"title":null,"description":"안녕하세요, 토스뱅크 Loan Tech Platform 팀에서 백엔드 개발 인턴으로 근무하고 있는 이경민, 문홍윤입니다.벌써 토스뱅크에 인턴으로 입사한 지 3개월이 지났습니다. 그동안 경험했던 토스뱅크의 개발 문화와 각자 진행한 프로젝트를 소개하고, 그 과정에서 느꼈던 고민과 배움들을 ...","urlSlug":"toss-bank-interns","primaryKeyword":{"id":48615,"content":"토스 인턴","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":53705,"content":"개발 인턴","wordType":"SEO_KEYWORD"},{"id":53707,"content":"인턴","wordType":"SEO_KEYWORD"},{"id":53709,"content":"토스뱅크","wordType":"SEO_KEYWORD"}],"tags":[]},"openGraph":{"title":"슬기로운 토스뱅크 개발 인턴 생활","description":"안녕하세요, 토스뱅크 Loan Tech Platform 팀에서 백엔드 개발 인턴으로 근무하고 있는 이경민, 문홍윤입니다.벌써 토스뱅크에 인턴으로 입사한 지 3개월이 지났습니다. 그동안 경험했던 토스뱅크의 개발 문화와 각자 진행한 프로젝트를 소개하고, 그 과정에서 느꼈던 고민과 배움들을 ...","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/photos/toss-bank-interns.jpg","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2599,"name":"이경민/문홍윤","slug":null,"shortDescription":null,"description":null,"imageUrl":null,"url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, 토스뱅크 Loan Tech Platform 팀에서 백엔드 개발 인턴으로 근무하고 있는 이경민, 문홍윤입니다.\n벌써 토스뱅크에 인턴으로 입사한 지 3개월이 지났습니다. 그동안 경험했던 토스뱅크의 개발 문화와 각자 진행한 프로젝트를 소개하고, 그 과정에서 느꼈던 고민과 배움들을 이 글에 정리해보려 해요.\n저희는 ","fullDescription":"안녕하세요, 토스뱅크 Loan Tech Platform 팀에서 백엔드 개발 인턴으로 근무하고 있는 이경민, 문홍윤입니다.\n벌써 토스뱅크에 인턴으로 입사한 지 3개월이 지났습니다. 그동안 경험했던 토스뱅크의 개발 문화와 각자 진행한 프로젝트를 소개하고, 그 과정에서 느꼈던 고민과 배움들을 이 글에 정리해보려 해요.\n저희는 ‘금융’이라는 다소 낯선 도메인 위에서, 빠르게 움직이는 팀의 일원으로 각자의 역할과 프로젝트를 수행하며 조금씩 성장해 나갈 수 있었습니다. 처음 접하는 기술과 환경 속에서 어려움도 있었지만, 그 모든 순간이 저희에겐 좋은 자극이 되었고, 앞으로 어떤 개발자가 되고 싶은지 진지하게 고민할 수 있는 계기가 되었어요.\n그 결과, 인턴 최초로 서버 챕터 발표 무대에 설 수 있었던 특별한 경험까지 할 수 있었고, 이 과정에서 배운 것들을 기록으로 남기고자 합니다. 이 글이 토스에 관심 있는 분들이나 인턴십을 고민 중이신 분들께 조금이나마 도움이 되길 바랍니다.\nLoan Tech Platform Team\n저희가 속한 Loan Tech Platform Team은 대출 도메인의 시스템을 효율적인 구조로 재설계하여 개발 생산성을 올리는 팀입니다. \n\n비효율적인 요소를 개발자들과의 인터뷰를 통해서 적극적으로 발굴하고 비효율을 제거합니다.\n버그를 방지하기 위한 테스트 플랫폼을 제안하고 운영유지보수 합니다.\nLoan Domain이 적은 비용으로 안정적으로 확장 가능한 시스템을 갖출 수 있도록 시스템을 재설계합니다.\n새로 입사한 개발자가 Soft landing을 하기 위해 필요한 문서화를 지원합니다.\nLoan Domain Weekly를 운영하고 좋은 개발 지식을 전파하는데 앞장섭니다.\n\n개발 프로젝트 소개\n변수명 플러그인 by 이경민\n저는 “비효율적인 요소를 발굴 및 제거합니다”라는 팀의 목표에 맞게 플러그인을 개발했습니다.\n처음 은행 도메인을 접하면서 가장 어려웠던 점은 변수명을 보고도 무슨 의미인지 직관적으로 이해하기 어려운 경우가 많다는 점이었어요. 특히 도메인 특성상 복잡한 개념을 다루다 보니, 변수명은 길어지고, 사용하는 단어들도 낯설었죠.\ninstallmentRepaymentManagementNumber / principalRepaymentCycle /\nrefinancingFailReasons 같은 단어는 한눈에 파악하기 어려움\n또한 새로운 변수명을 만들 때 어떤 표현이 더 자연스러운지, 또 기존에 사용된 변수명이 있는지를 확인하고 중복되거나 어색한 이름을 피하는 것이 쉽지 않았어요.\n이자계산 같은 단어도 → / calculateInterest / interestCalculation / getInterestCalculation 등 다양한 표현 중 어떤것을 사용하는지를 파악하기 어려움\n\n\nDB에 프로젝트에서 사용되는 변수명과 뜻을 저장하고 IDE 플러그인을 사용해서 쉽게 변수명을 만들고 영단어 뜻을 알 수 있게 하자!\n\n플러그인 동작 흐름 요약\n\n사용예시\nIDE에서 드래그 하고 단축키를 누르기만 하면 됩니다. \n\n입력 단어 전처리\n기본적으로 DB에는 단어별로 뜻이 저장되어 있습니다. ex) 원금→principle, 상환→repayment\n하지만 보통 검색하는 단어는 합성단어인 경우이기 때문에 단어를 자동으로 분리하는 기능이 필요해요.\nimport org.openkoreantext.processor.OpenKoreanTextProcessorJava\n\nobject VariableProcessor {\n fun preprocess(word: String): String {\n val spaced = when {\n word.matches(Regex(\"^[가-힣 ]+$\")) -> processKorean(word)\n word.matches(Regex(\"^[a-zA-Z ]+$\")) -> processEnglish(word)\n else -> word\n }\n return spaced\n }\n\n private fun processKorean(word: String): String {\n val normalized = OpenKoreanTextProcessorJava.normalize(word)\n val tokens = OpenKoreanTextProcessorJava.tokenize(normalized)\n return OpenKoreanTextProcessorJava.tokensToJavaStringList(tokens).joinToString(\" \")\n }\n\n private fun processEnglish(word: String): String {\n return word.split(Regex(\"(?=[A-Z])\")).joinToString(\" \").trim()\n }\n}\n한국어 → 영어 번역\nNLP(OpenKoreanTextProcessorJava)를 사용해서 합성 단어를 단어로 분리해서 DB를 조회합니다\nex) “원금상환주기” → “원금 상환 주기”\n영어 → 한국어 번역\n보통 변수명은 CamelCase(단어가 합쳐진 부분마다 맨 처음 글자를 대문자로 표기)로 만들어져 있기 때문에 대문자를 기준으로 단어를 분리해서 단어를 조회합니다.\nex) “CamelCase” → “Camel Case”\n\nLLM 사용\n하지만 검색한 단어가 DB에 없을수도, 오타로 인해 원하는 단어를 검색 못할 가능성도 있습니다. 이럴 경우를 대비하여 새로운 단어의 추천, 오타 검증을 토스뱅크 내부에서 자체 구축된 LLM를 통해 지원했습니다.\n새로운 단어 추천\n\n검색한 단어들 중 DB에 존재하는 단어는 지원합니다.\nDB에 없는 단어는 앞뒤 문맥을 통해 LLM이 단어를 추천합니다. \n\n앞뒤 문맥을 통한 단어 번역\n\n이처럼 똑같은 단어를 번역해도 앞 뒤 문맥을 보고 문맥상 더 적합한 단어를 추천해요.\n\n오타 검증\n\n오타는 앞 뒤 문맥을 보고 조정 후 단어를 검색합니다\nex) “ 상활주기” → “상환주기” → “repaymentCycle”\n\n플러그인 도입 결과\n내부 피드백\n사전 데이터 확대\nWisemeta에 있는 오라클 메타 단어 (~7만 개)도 등록하면 유용할 것 같다는 의견\n매번 IDE에서 찾기 번거로우므로 사전화가 필요\n성능 최적화 제안\n단어 정보는 자주 바뀌지 않으므로, DB 대신 로컬 메모리 캐시를 활용하는 방식이 효율적\n변경이 발생할 경우에는 캐시를 Evict하는 구조로 개선 가능\n단어 수가 아주 많지 않다면, 굳이 DB 없이 파일 기반으로 관리해도 된다는 제안도 있음\n사용성 개선 피드백\n마우스 없이 키보드로 선택 박스 이동 가능하도록 개선하면 더 편리할 것\nLLM 추천 결과는 별도로 구분하지 않고, 바로 아래에 함께 보여주는 방식이 더 자연스러움\n\n실제 사용 후기\n새로운 변수명 작성이 쉬워짐\n예: \"신속채무조정\" → fastDebtAdjustment\n자연스러운 변수명 추천이 가능해졌고, 작명 스트레스가 줄어듦\n기존 코드 이해에 도움\n익숙하지 않은 변수명도 뜻을 빠르게 파악할 수 있어, 도메인 이해 속도 향상\n새로운 개발자가 온보딩할 때 초기 진입장벽을 낮춰줌\n팀 내 컨벤션 관리 수단으로 활용\nAdmin 페이지를 통해 단어를 손쉽게 등록·수정할 수 있음\n이를 통해 스쿼드 단위의 변수명 컨벤션을 자율적으로 관리 가능, 실제로 몇몇 스쿼드에서 운영중\n\n이 플러그인은 단순히 변수명을 추천하는 것을 넘어, 조직 내 변수명 컨벤션을 일관되게 유지하고, 신규 개발자의 도메인 적응 속도를 높이는 데 실질적인 도움을 줄 수 있어요. 향후에는 사용자 검색 이력을 바탕으로 한 추천 강화, 사내에서 사용되는 용어를 자동 학습하는 기능 등으로 지속적인 확장 가능성도 염두에 두고 있습니다.\n\n\nSecretToString 플러그인 by 문홍윤\n개발을 하다 보면, 로그나 디버깅 과정에서 객체를 문자열로 출력하는 일이 많습니다. Kotlin의 data class는 이때 사용할 수 있는 toString()을 자동으로 생성해주는데, 편리한만큼 잠재적인 위험이 있습니다. 예를 들어, 계좌번호나 주민등록번호 같은 민감한 정보도 그대로 노출될 수 있죠.\n\n현재 토스뱅크는 이러한 문제에 대응해 다음 정책을 사용하고 있어요.\n\n마스킹이 필요한 프로퍼티에 @Secret 애노테이션을 추가\n로깅시 SecretUtils.toString() 라는 자체 메서드를 사용해서, @Secret 이 설정된 프로퍼티는 마스킹해서 출력합니다.\n\n하지만 이 방식들은 공통적으로 개발자가 반드시 마스킹 유틸리티나 애노테이션을 올바르게 적용해야만 동작합니다. 즉, 누군가 실수로 일반 toString() 을 그대로 로그에 출력하거나, @Secret 애노테이션을 깜빡하고 빠트렸다면 민감정보가 고스란히 로그에 남게 돼요. 물론 배포 전에 검증 과정을 거치므로 실제로 이런 일이 일어나지는 않지만, 같은 코드를 반복해서 검수하고 수정하는 것은 상당히 번거로운 작업입니다.\n이 문제를 해결해보고자, Kotlin 컴파일러 플러그인으로 Secret-ToString-Plugin을 만들었어요.\n\n아이디어\n애초에 @Secret 프로퍼티가 있는 data class에 대해 미리 toString()을 오버라이딩해서 마스킹 로직을 직접 구현해두면 이런 문제가 생기지 않습니다. 이 방식이 가장 명시적이고, IDE에서 코드도 그대로 보이기 때문에 예측가능성도 높죠.\n하지만 현실적으로는 수정해야 할 data class가 너무 많았고, 그중 일부는 공용 라이브러리나 여러 모듈에 흩어져 있었어요. 하나하나 수동으로 toString()을 작성하는 것은 반복적이고 오류 가능성이 높은 작업이었고, 유지보수 난이도도 크게 올라갈 수밖에 없었습니다.\n이 문제를 어떻게 해결할지 고민하던 중, 자연스럽게 Java 생태계에서 널리 쓰이는 \nhttps://projectlombok.org/이 떠올랐습니다. \n\nLombok은 toString() 이나 equals() 와 같은 반복적인 코드를 컴파일 시점에 자동으로 생성해주는 툴입니다. 덕분에 개발자는 @Data나 @Getter/@Setter 같은 애노테이션 몇 개만 붙이면 필요한 코드를 거의 다 해결할 수 있었고, 수동으로 작성할 때 생기는 실수를 줄일 수 있어요.\n\n\n그렇다면 비슷하게, @Secret을 감지해 data class에 자동으로 toString()을 생성해주면 어떨까?\n결국 이 아이디어가 구체화되면서, 빌드 시점에 toString()을 통째로 갈아끼워서 마스킹을 보장하는 컴파일러 플러그인을 만드는 쪽으로 방향이 정해졌어요.\n\nSecret-ToString-Plugin\n이 플러그인의 장점은, 적용이 굉장히 간단하다는 점입니다. 어떤 특별한 유틸리티 호출이나 별도의 복잡한 설정도 필요하지 않아요.\ndata class Test(\n\t@Secret val name: String\n)\n\nval test = Test(토뱅이)\n\n// AS-IS\nprintln(test) // -> Test(name=토뱅이)\n\n// TO-BE\nprintln(test) // -> Test(name=****)\n위 예제를 보시면, 플러그인을 적용했을 때와 적용하지 않았을 때의 차이를 바로 확인할 수 있습니다.\n별도의 유틸리티 호출 없이, 기본 toString()이 자동으로 마스킹된 형태로 재정의됩니다. 즉, 개발자는 그냥 평소처럼 println(test)를 쓰면 되고, 플러그인이 알아서 안전하게 출력해 주기 때문에 실수할 여지가 거의 없어요.\n\n작동 원리 : IR (Intermediate Representation) 조작 \nKotlin 컴파일러는 소스 코드를 처리할 때 대략 다음 단계를 거칩니다:\n파싱 / 타입체크 : \n변수, 함수, 클래스의 타입과 구조를 해석하고 검증합니다.\nIR 생성\n코드의 구조와 동작을 표현하는 IR 트리를 생성합니다.\n바이트코드 생성\nJVM 바이트코드를 생성합니다.\nSecret-ToString-Plugin은 이 중 IR 생성 이후 단계에서 동작합니다. Java의 Lombok은 더 이른 단계에서 코드를 삽입하지만, Kotlin은 공식 API를 통해 이미 타입과 심볼이 확정된 IR을 안전하게 수정할 수 있어요. 실무적으로 모든 프로퍼티와 함수 등을 직접 참조할 수 있어 구현 및 로직이 단순해지고, 다른 빌드 파이프라인과 충돌하지 않는 장점이 있습니다.\nSecret-ToString-Plugin의 동작 흐름은 다음과 같습니다.\n1️⃣ IR 트리 순회\n모든 data class를 탐색합니다.\n\n2️⃣ 애노테이션 탐색\n각 프로퍼티에 @Secret 어노테이션이 붙어있는지 검사합니다.\n마스킹 대상 클래스라면 처리 목록에 추가합니다.\n\n3️⃣ 기존 toString() 제거\n컴파일러가 자동 생성한 기본 toString() 함수를 찾아 삭제합니다.\n\n4️⃣ 새로운 toString() 생성\n먼저 toString()의 시그니처들을 정의합니다.\n다른 클래스에서 이 함수를 참조할 때 필요한 일종의 “포인터”입니다.\n\n다음으로 바디를 생성해 실제 출력 로직을 작성합니다.\n실제 어떤 동작을 하는지 적어놓은 “구현 내용”입니다.\n@Secret 프로퍼티는 항상 마스킹 로직을 거쳐 출력합니다.\n나머지 프로퍼티는 본래 값을 출력하거나, 객체일 경우 그 객체의 toString() 시그니쳐를 참조해 호출합니다.\n\n바디를 만들 때 참조 대상에 toString()시그니처가 존재하지 않으면 컴파일 과정에서의 NPE가 발생하기 때문에, 먼저 모든 시그니처를 생성해둔 뒤 바디를 만드는 순서로 구현했습니다.\n\n실제 환경에서는?\n처음에는 “모든 data class에 전면 적용해버리면, 유틸리티를 깜빡하는 문제가 원천 차단되겠다”는 아이디어로 시작했습니다.\n그러나 팀 내에서 논의해 본 결과, 몇 가지 중요한 우려가 제기되었어요:\n코드에 표시되지 않는 자동 동작이 지나치게 많으면 추적성이 떨어진다.\n새로운 개발자나 다른 팀에서는 플러그인의 존재를 모르고 예상치 못한 출력 때문에 디버깅이 어려워질 수 있다.\n결국 이런 리스크를 고려해 보수적인 접근 방식을 채택했습니다:\n@SecretToString 애노테이션이 달린 클래스에만 기능 적용\n적용하는 레포지토리와 팀의 판단 하에 옵션을 주어 전체 data class에 일괄 적용 가능\n이 경우 @DisableSecretToString으로 일부 클래스만 예외 처리\n이렇게 해서 필요한 범위에만 명확한 의도를 표시해 안전망을 만들 수 있고, 코드에 의도가 드러나기 때문에 협업에서 혼란을 줄일 수 있었습니다.\n도입 결과\n이 프로젝트로 인해, SecretUtils.toString() 을 누락하는 것은 어느 정도 해결했으나, 애초에 @Secret 을 선언 시 빠트리는 문제는 완전히 해결하지 못했어요. 분량 상 이 글에서 설명은 못했지만, 이를 개발 단계에서 패턴 매칭 등을 이용해 자동으로 감지하는 별개의 프로젝트도 진행해 여신 도메인에 적용했습니다.\n무엇보다 이 두 개선은 보안을 강화하는 데 그치지 않고, 민감 정보 처리에 대한 개발자의 부담을 근본적으로 줄이는 계기가 되었어요. 짧은 기간이었지만, 실제 프로덕션 환경에 적용되어 팀 전체의 개발 프로세스를 한층 더 견고하고 효율적으로 만드는 데 기여할 수 있었던 점이 큰 보람으로 남습니다.\n\n토스 인턴 분들이 궁금해요\n\nQ. 지금은 어떤 일을 하고 계신가요?\n경민: 저는 Loan Tech Platform에서의 일도 정말 즐거웠지만, 토스뱅크에 온 만큼 은행 도메인 자체를 깊이 경험해보고 싶었어요. 고민 끝에 팀 이동을 요청드렸고, 흔쾌히 승인해 주신 덕분에 지금은 CPL(기업부동산스쿼드)에서 활동하고 있어요. CPL은 은행 도메인 중에서도 특히 복잡한 영역이라 처음 이해하는 데 어려움을 겪었지만, 팀원 분들의 적극적인 도움 덕분에 빠르게 적응할 수 있었어요. 지금은 LTI, RTI 같은 대출 규제 관련 로직을 직접 담당하며 개발에 참여하고 있어요.\n\n홍윤: 저는 Loan Tech Platform에서 하는 일이, 작은 개선 하나에도 여러 팀에 파급력이 미친다는 점이 늘 걱정되어 조심스러워지면서도 동시에 흥미로웠어요. 그래서 경민님과는 다르게 계속 이 팀에 남아 더 다양한 작업을 하기로 했어요. 그 이후에는 여신 도메인에서 공통으로 사용하는 다양한 설정값을 한 곳에서 관리할 수 있게 하는 서버를 새롭게 만들어 배포하고, 여기에 연계되어 실시간으로 바뀔 수 있는 설정값들을 접근할 수 있는 라이브러리를 개발했어요. 그 과정에서 토스뱅크에서 사용하는 다양한 기술들을 익히며, 효율적이면서 장애상황 등에서도 안정적으로 동작할 수 있는 로직을 구현하는 등, 다양한 프로젝트에 참여하고 있어요.\n\nQ. 토스에서의 생활이 궁금해요!\n경민: 토스에는 DRI(Directly Responsible Individual)라는 문화가 있어요. 최소한의 일만 정해주고, 나머지는 스스로 문제를 정의하고 해결하는 구조인데요, 덕분에 인턴임에도 여러 프로젝트를 직접 리드하며 경험해볼 수 있었어요. 처음에는 최종 의사결정까지 책임져야 한다는 점이 부담스럽게 느껴졌지만, 팀원들과 초안을 공유하고 피드백을 주고받는 과정을 거치며 더 나은 방향을 함께 고민할 수 있었어요. 그렇게 점차 책임감을 갖고 주도적으로 일하는 방식에 익숙해졌고, 제가 원하는 방향으로 문제를 해결해나가며 빠르게 성장하고 있다고 느끼고 있어요.\n\n홍윤: 저는 토스의 가장 큰 장점은 수평적인 개발 문화에 있다고 생각해요. 단순히 남이 시키는 일을 하라는 대로 하는게 아니라, 인턴임에도 의견을 제안하거나 로직을 개발할 때 다른 선배 개발자분들과 토의하는 일이 많았어요. 그 과정에서 제가 생각해보지 못했던 시각이나 더 나은 방법을 자주 접하게 되었는데, 덕분에 이전보다 더 주도적으로 새로운 기술을 시도하고 학습하거나, 익숙하지 않은 영역도 빠르게 익히려는 태도가 자연스럽게 생긴 것 같아요.이런 환경에서 인턴을 하다 보니, 단순히 주어진 일을 처리하는 것을 넘어 어떻게 하면 더 좋은 방향으로 문제를 풀 수 있을지 고민하고, 직접 제안하고 실행하는 경험을 많이 쌓는 것 같아요\n\n\n\n\n\nQ. 토스에서 좋았던 점은 무엇인가요?\n경민: 토스에서의 생활은 개발자로 성장하기에 정말 최적의 환경이라고 느꼈어요. 개발 환경 세팅부터 온보딩 시스템까지 체계적으로 잘 마련되어 있어서, 처음 시작할 때도 큰 어려움 없이 적응할 수 있었어요. 필요하다면 서적이나 교육 자료도 자유롭게 활용할 수 있었고, 주변에 계신 뛰어난 팀원분들과의 커뮤니케이션을 통해 실무적인 경험도 자연스럽게 얻을 수 있었어요. 또한, 사내 커피숍이나 편의점, 휴게 공간 같은 복지 시설 덕분에 개발에만 온전히 집중할 수 있는 환경이 만들어졌다고 느꼈어요.\n\n홍윤: 저는 이론적인 부분만 공부해왔어서, 개발 경험이 거의 없던 상태로 인턴으로 입사했어요. 그래서 적응을 못할까봐 걱정이 꽤 많았었는데, 입사하고 보니 의미없는 고민이었던 것 같아요. 신규 입사자를 위해서 토스뱅크의 전체적인 환경 설정, 구조, 사용하는 기술 등이 너무 체계적으로 잘 정리되어 있었고 , 무엇보다 메이트분들이 적극적으로 이것저것 알려주려 하셔서 적응에 어려움이 거의 없었어요. 덕분에 토스의 환경에 빨리 익숙해졌고, 온전히 저의 역량을 키우고 프로젝트에 집중할 수 있었어요.\n\nQ. 마지막으로 하고 싶은 말\n경민: 많이 부족하고 서툴렀던 첫 인턴이었지만, 토스에서의 경험은 제가 어떤 개발자로 성장해나가야 할지 방향을 명확하게 잡을 수 있었던 계기였어요. 작은 기능 하나를 구현할 때도 단순히 동작하게 만드는 것을 넘어서, “왜 이 기능이 필요한가?”, “더 나은 방식은 없을까?” 라는 질문을 끊임없이 던지게 되었고, 이런 고민은 곧 기술적인 해결 능력은 물론, 제품 관점에서 사고하는 습관으로 이어졌어요. 토스에서의 인턴십은 단순히 코드를 작성해보는 경험을 넘어서,문제를 주도적으로 정의하고 해결하는 개발자로 성장할 수 있도록 만들어준 정말 소중한 기회였어요.\n\n홍윤: 책으로 기술을 배우는 것만으로는 채울 수 없는 배움으로 가득찼던 시간이었어요. 처음에는 어떻게든 주어진 기능을 실수 없이 구현하는 것에만 집중했는데, 점점 더 “왜 이 방식이어야 하는지”, “이게 정말 좋은 방향인지”를 스스로 물어보게 됐던 것 같아요. 그 과정에서 단순히 잘 동작하는 코드를 넘어서, 직관적인 논리 흐름과 확장 가능성 등 더 다양한 요소를 고려하는 개발을 하게 됐어요. 무엇보다도 인상적이었던 건, 누구나 아이디어를 제안할 수 있고 그 아이디어를 자유롭게 구현해볼 수 있었던 문화 덕분에 스스로 책임감을 가지고 일을 끝까지 밀어붙이는 경험을 할 수 있었어요. 당연히 아직 부족한 점이 많지만, 앞으로도 이렇게 문제를 주도적으로 정의하고 더 나은 해답을 찾으려는 태도를 계속 가져가고 싶어요.\n","isDisplayingFeedback":false,"quizzes":[],"opinionForm":null,"viewCount":16357},{"id":37777,"updatedTime":"2025-08-28T03:42:45+09:00","createdTime":"2025-06-23T13:15:03+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""},{"name":"인기글","id":1058,"slug":null,"parentId":null,"iconUrl":null}],"series":null,"seriesSlug":null,"title":"토스페이먼츠 결제 시스템 연동을 돕는 MCP 서버 구현기","subtitle":"AI 기반 코딩 도구를 활용해서 토스페이먼츠 결제 시스템을 쉽고 빠르게 연동할 수 있도록, MCP 서버를 구현한 과정과 인사이트를 공유합니다.","bottomButtonConfig":{"ctaType":"EMPHASIS_TEXT","imageUrl":null,"imageAlt":null,"title":"토스페이먼츠 연동 MCP 서버 사용하기","description":"토스페이먼츠 연동 MCP 서버는 MCP 프로토콜을 지원하는 다양한 클라이언트에서 사용할 수 있어요.","ctaName":"결제 연동 가이드 문서 확인하기","landingUrl":"https://docs.tosspayments.com/guides/v2/get-started/llms-guide","isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":"supertoss://web?url=https%3A%2F%2Fdocs.tosspayments.com%2Fguides%2Fv2%2Fget-started%2Fllms-guide%3F&external=true&clearHistory=true&swipeRefresh=true","landingExternal":"https://docs.tosspayments.com/guides/v2/get-started/llms-guide"},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts/mcp_businessfeed_tnail.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"tosspayments-mcp","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-06-24T15:56:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":37777,"title":null,"description":"안녕하세요, 토스페이먼츠 김용성, 하태호입니다. 지난주, 토스페이먼츠에서 PG업계 최초로 MCP를 소개하면서 많은 분들이 관심가져 주셨는데요. 이 글을 통해 MCP 서버 구현 과정과 그 안에서 얻은 러닝을 공유하고자 해요.","urlSlug":"tosspayments-mcp","primaryKeyword":{"id":52997,"content":"MCP","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":37528,"content":"토스페이먼츠","wordType":"SEO_KEYWORD"},{"id":37582,"content":"AI","wordType":"SEO_KEYWORD"},{"id":53011,"content":"결제 시스템","wordType":"SEO_KEYWORD"}],"tags":[{"id":37580,"content":"AI","wordType":"TAG"},{"id":52999,"content":"MCP","wordType":"TAG"}]},"openGraph":{"title":"토스페이먼츠 결제 시스템 연동을 돕는 MCP 서버 구현기","description":"안녕하세요, 토스페이먼츠 김용성, 하태호입니다. 지난주, 토스페이먼츠에서 PG업계 최초로 MCP를 소개하면서 많은 분들이 관심가져 주셨는데요. 이 글을 통해 MCP 서버 구현 과정과 그 안에서 얻은 러닝을 공유하고자 해요.","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/illusts/mcp_businessfeed_tnail.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2026,"name":"김용성","slug":"kys0213","shortDescription":"토스페이먼츠 Node.js Developer","description":"-","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":2,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, 토스페이먼츠 김용성입니다.\n지난주, 토스페이먼츠에서 PG업계 최초로 MCP를 소개하면서 많은 분들이 관심가져 주셨는데요. 이 글을 통해 MCP 서버 구현 과정과 그 안에서 얻은 러닝을 공유하고자 해요.\n요약 \n\n토스페이먼츠의 API 연동을 조금이라도 더 쉽고 빠르게 하기 위해, AI 기반 코딩 도구 활용시 도","fullDescription":"안녕하세요, 토스페이먼츠 김용성입니다.\n지난주, 토스페이먼츠에서 PG업계 최초로 MCP를 소개하면서 많은 분들이 관심가져 주셨는데요. 이 글을 통해 MCP 서버 구현 과정과 그 안에서 얻은 러닝을 공유하고자 해요.\n요약 \n\n토스페이먼츠의 API 연동을 조금이라도 더 쉽고 빠르게 하기 위해, AI 기반 코딩 도구 활용시 도움이 될 수 있도록 토스페이먼츠 연동 MCP 서버를 제공합니다. 자세한 내용은 토스페이먼츠 연동 가이드를 참고하세요.\n토스페이먼츠 연동 MCP 서버를 활용하면 AI 기반 코딩 도구를 단독으로 사용할 때보다 연동 코드 생성 정확도가 높아집니다.\n토스페이먼츠 연동 MCP 서버는, 길드(guild) 내 작은 논의에서 시작된 아이디어로부터 구현되어 글 작성 시점에 AI 모델에게 제공되는 지원되는 맥락 정보가 부족할 수 있습니다. 토스페이먼츠의 API 연동 경험이 더 나아질 수 있도록 계속해서 개선해 나가 볼게요.\n본 글에는 코드가 많이 첨부되어 있어 내용이 길어요. 자세한 내용이 궁금하신 분은 PC 환경에서 읽어보시기를 권장드립니다.\n* 길드(guild): 서로 다른 팀이나 사일로에 속한 팀원들이 느슨하게 모여 공통의 관심사를 공유하는 조직\n\n먼저 이해를 돕기 위해 짧은 시연 영상을 준비했어요. 외부 개발자분들이 토스페이먼츠 MCP를 활용해서 주문서 페이지를 만드는 상황에 대한 예시입니다. 로딩이나 일부 수정 과정은 생략했고, Claude 4 모델을 사용했습니다.\n\n구현 배경\n토스페이먼츠는 출범 초기부터 어떻게 하면 고객사가 결제 시스템을 더 쉽게 연동할 수 있을지에 대한 고민이 많았습니다. 기존의 결제 시스템 연동 방식은 개발자에게 복잡하고 번거로운 작업이라는 인식을 풀어야 했기 때문이죠.\n이 문제를 해결하기 위해 직관적인 API와 SDK를 새로 만들고, 토스페이먼츠 결제 시스템을 연동하는 개발자들을 위한 개발자 센터를 만드는 등 다양한 활동을 수행하였고, 개발자분들로부터 좋은 피드백을 받았습니다.\n그렇지만 여전히 결제 시스템 연동의 어려움을 겪는 분들이 많이 계신데요, 개발팀이 따로 없는 작은 가맹점이나 외부에 개발을 맡긴 사업자분들이 특히 어려움을 겪고 있었습니다. AI 기반 코딩 도구를 활용하면 토스페이먼츠 연동을 더 쉽게 할 수 있지 않을까?하는 생각을 바탕으로 토스페이먼츠 연동 코드를 작성해 보았지만, 생성된 코드의 정확도가 많이 떨어지는 문제가 있었어요.\n이 문제를 해결하기 위한 고민을 하던 중, AI 모델이 이해할 수 있는 맥락 정보를 제공할 수 있는 방법인 MCP(Model-Context Protocol)라는 개념이 등장해서 이를 활용해보기로 했습니다.\n\nMCP란?\n\nMCP는 엔트로픽에서 제안한, 인공지능 모델(LLM)이 다양한 상황과 맥락을 잘 이해할 수 있도록 돕는 표준적인 방법입니다. USB가 컴퓨터와 주변기기들을 간편하게 연결할 수 있는 표준을 만들었던 것처럼, MCP는 AI 모델과 다양한 환경이 자연스럽게 연결될 수 있도록 돕습니다. MCP 덕분에 하나의 서버에서 다양한 AI 툴(예: Cursor, Claude, Windsurf 등)을 편하게 사용할 수 있게 되는 것이죠. 저희는 MCP를 활용해, 개발자들이 더 쉽고 즐겁게 작업할 수 있는 '바이브 코딩' 환경을 만들려고 하고 있어요.\n\n양질의 콘텐츠 준비하기 \nMCP에서 가장 중요한 건, AI가 잘 이해할 수 있는 콘텐츠를 전달하는 것입니다. 하지만 모든 제품에 대해 콘텐츠를 개별적으로 제작하는 건 시간과 비용이 너무 많이 들죠. 다행히 저희는 이미 MDX 기반의 개발자 센터를 운영하고 있었고, CI/CD 과정에 CDN에 배포되는 구조라서 MCP 서버가 해당 콘텐츠에 접근한다면 문서의 버전업을 그대로 따라가는 구조를 충족할거라 생각했습니다. 이를 기반으로 LLM이 잘 이해할 수 있도록 llms.txt 파일을 만들어 프로토타입을 빠르게 구축할 수 있었어요. 특히 이 과정에서 프론트엔드 챕터의 신지호님께서 큰 도움을 주셨습니다.\nllms.txt는 대규모 언어 모델(LLM)이 웹사이트 콘텐츠를 더 잘 이해하고 상호 작용할 수 있도록 돕는 제안된 표준 파일이에요. 이 파일은 LLM이 웹사이트의 문서, 코드베이스 등과 어떻게 상호 작용해야 하는지에 대한 정보를 제공하여 LLM 기반 도구와 서비스의 효율성을 높이는 데 사용됩니다.\n* 참고: https://llmstxt.org/\n\nMCP Transport 결정하기 \n처음에는 Websocket이나 SSE 기반의 Remote MCP도 고려했지만 로컬 기반의 MCP 서버를 구현하기로 결정했어요. 로컬 기반 MCP 서버를 사용하며 얻을 수 있었던 장점들은 아래와 같습니다.\n\nCDN에 업로드된 개발자 센터 문서를 기반하므로 SSOT(Single Source of Truth)달성 가능\n사용자가 늘어나도 각 유저의 로컬 장비에서 실행하므로 서버 비용 발생 없음\nMCP 스펙에 STDIO Transport가 존재함\nNPM에 배포하여 이미 검증된 패키지 매니저를 사용하므로 추가 관리 비용 없음\n\n첫 번째 버전\nllms.txt에 기반하여 사전의 정의된 키워드 기반으로 문서를 검색하는 방식으로 구현하였습니다.\n\n\n도구 목록\n프로토타입은 아래 4개의 도구를 지원하였고, LLM은 이 도구들을 사용하여 토스페이먼츠 개발자 센터 문서를 탐색해요.\n\nget-keywords\ndocuments-by-keywords\ndocuments-by-link\ndocument-by-id\n\nget-keywords\n사전에 정의된 키워드 목록을 반환하는 도구입니다. LLM은 조회한 키워드 목록을 보고 사용자 질의를 분석하여 적절한 키워드를 추출 후 docs-by-keywords를 호출합니다.\nDescription\n\n반드시 먼저 호출하여 지원하는 키워드를 조회하세요. 조회된 키워드를 바탕으로 사용자의 질문에서 키워드를 추출합니다.\nResponse\nblog: \"토스페이먼츠 공식 블로그 게시글입니다.\"\ncodes: \"연동 시 사용하는 데이터 타입, ENUM 코드, 기관 코드 등을 정리한 문서입니다.\"\nguides: \"개발자가 참고할 수 있는 연동 가이드 문서입니다.\"\nresources: \"제품 설명과 범용 규약을 정리한 문서입니다.\"\nreference: \"연동 시 참조할 수 있는 참고용 문서입니다.\"\nsdk: \"토스페이먼츠 SDK 관련 문서입니다.\"\nlegacy: \"LG U+ 관련 레거시 시스템 문서입니다.\"\npayment-widget: \"결제 위젯 관련 문서입니다.\"\npayment-window: \"결제창 관련 문서입니다.\"\nbilling: \"정기결제 관련 문서입니다.\"\nbrandpay: \"브랜드페이 관련 문서입니다.\"\nquick: \"퀵 계좌이체 연동 문서입니다.\"\n결제위젯: \"결제 위젯 관련 문서입니다.\"\n결제창: \"결제창 관련 문서입니다.\"\n퀵계좌이체: \"퀵 계좌이체 연동 문서입니다.\"\n빌링: \"정기결제 관련 문서입니다.\"\n브랜드페이: \"브랜드페이 관련 문서입니다.\"\nv1: \"v1 버전의 문서입니다.\"\nv2: \"v2 버전의 문서입니다.\"\n\ndocuments-by-keywords\nLLM 키워드를 적절하게 추출하여 질의하면, MCP 서버가 문서들을 순회하며 다양한 조건별 점수를 계산하고 상위 10개의 문서를 반환하는 도구입니다.\n내부 동작 코드\nexport class TossPaymentsDocument {\n constructor(\n private readonly rawDocs: RawDocs,\n private readonly keywordSet: Set,\n public readonly id: number\n ) {}\n \n ...\n \n scoreByKeywords(keywords: Keyword[]): number {\n\t return keywords\n\t .map((keyword): number => {\n\t if (this.keywordSet.has(keyword)) {\n\t // 키워드별 가중치 \n\t return KeywordWeightConfig[keyword] ?? 1;\n\t }\n\t\n\t if (keyword === \"v1\" || keyword === \"v2\") {\n\t return -1;\n\t }\n\t\n\t if (this.rawDocs.text.includes(keyword)) {\n\t return 0.3;\n\t }\n\t\n\t return 0;\n\t })\n\t .reduce((previousValue, currentValue) => previousValue + currentValue, 0);\n\t }\n}\nexport class TossPaymentDocsRepository {\n constructor(private readonly documents: TossPaymentsDocument[]) {}\n \n async getTopMatchedDocumentsByKeywords(\n keywords: Keyword[],\n topN: number = 10\n ): Promise {\n const scoredDocs = this.documents\n .map((doc) => ({ doc, score: doc.scoreByKeywords(keywords) }))\n .filter(({ score }) => score > 0) // 매칭이 아예 없는 문서는 제외\n .sort((a, b) => b.score - a.score) // 점수 높은 순 정렬\n .slice(0, topN); // 상위 N개만 반환\n\n return scoredDocs.map(({ doc }) => doc);\n }\n}\nDescription\n키워드 목록을 기반으로 관련된 문서들을 조회합니다. 반드시 get-keywords 에서 조회한 키워드로 탐색해야합니다. 만약 버전정보를 확인할 수 없으면 v2 를 우선해서 사용해주세요.\n\n## 파라미터 형식\n{\n \"keywords\": string[] // UTF-8 인코딩된 문자열 배열\n}\n\n\n## 올바른 사용법 예시\n{\n \"keywords\": [\"sdk\", \"결제위젯\", \"v2\"]\n}\n\n{\n \"keywords\": [\"결제창\", \"v2\"]\n}\n\n\n## 파라미터 유효성 검사 규칙\n1. 반드시 JSON 객체여야 함\n2. keywords 필드는 필수이며 배열 타입이어야 함\n3. 배열의 각 요소는 UTF-8 인코딩된 문자열이어야 함\n4. 배열은 최소 1개 이상의 요소를 포함해야 함\n\n## 잘못된 사용 예시와 오류 메시지\n- [\"sdk\", \"결제위젯\"]\n ❌ Error: 최상위 레벨이 JSON 객체가 아님\n \n- { \"keywords\": \"결제위젯\" }\n ❌ Error: keywords 필드가 배열 타입이 아님\n \n- { \"keywords\": [1, 2] }\n ❌ Error: 배열 요소가 문자열 타입이 아님\n \n- { \"keywords\": [] }\n ❌ Error: keywords 배열이 비어있음\nResponse \nMCP 서버 내부에서 채번한 unique 한 id 와 제목, 문서 설명 정보를 반환합니다.\n1 [Android, iOS 웹뷰에서 딥링크 열기] 각 딥링크 유형의 특징과 차이점을 자세히 알아보고, Android와 iOS 웹뷰에서 딥링크로 국내 카드앱·은행앱으로 이동하는 예시를 살펴볼게요.\n2 [Basic 인증과 Bearer 인증의 모든 것] 비밀번호로 이메일 계정의 권한을 확인하는 것 처럼, HTTP 인증으로 서버에 접근하는 클라이언트의 권한을 확인해요.\n...\n\ndocuments-by-link\nLink 기반으로 문서를 탐색하는 도구입니다. LLM이 문서를 탐색하는 중에 Markdown 링크로 표현된 문서를 만나는 경우 탐색을 실시합니다.\n내부 동작 코드\n\nexport class TossPaymentsDocument {\n\n private readonly linkPath: string[];\n\n constructor(\n private readonly rawDocs: RawDocs,\n private readonly keywordSet: Set,\n public readonly id: number\n ) {\n this.linkPath = this.destructureLink(rawDocs.link);\n }\n \n ...\n \n scoreByLink(link: string): number {\n const destructureLink = this.destructureLink(link);\n\n return destructureLink\n .map((path, index): number => {\n const docPath = this.linkPath[index];\n\n if (!docPath) {\n return -1;\n }\n\n if (docPath === path) {\n return 2;\n } else if (docPath.startsWith(path) || path.startsWith(docPath)) {\n return 1;\n } else if (docPath.includes(path) || path.includes(docPath)) {\n return 0.1;\n }\n\n return 0;\n })\n .reduce((previousValue, currentValue) => previousValue + currentValue, 0);\n }\n \n private destructureLink(link: string) {\n if (link.endsWith(\".md\")) {\n link = link.slice(0, link.length - 3);\n }\n\n if (!link.startsWith(\"http\")) {\n link = `https://docs.tosspayments.com${\n link.startsWith(\"/\") ? link : `/${link}`\n }`;\n }\n\n const url = new URL(link);\n return url.pathname\n .split(\"/\")\n .filter((part) => part !== \"\")\n .reverse();\n }\n}\nexport class TossPaymentDocsRepository {\n constructor(private readonly documents: TossPaymentsDocument[]) {}\n \n ... \n \n async getTopMatchedDocumentsByLink(\n link: string,\n topN: number = 10\n ): Promise {\n const alias = LinkAlias[link];\n\n if (alias) {\n link = alias;\n }\n\n const scoredDocs = this.documents\n .map((doc) => ({ doc, score: doc.scoreByLink(link) }))\n .filter(({ score }) => score > 0) // 매칭이 아예 없는 문서는 제외\n .sort((a, b) => b.score - a.score) // 점수 높은 순 정렬\n .slice(0, topN); // 상위 N개만 반환\n\n return scoredDocs.map(({ doc }) => doc);\n }\n}\nDescription\n문서 링크를 입력하여 문서의 상세 내용을 조회합니다. 마크다운 문법에서 link syntax 로 정의된 링크를 입력해주세요.\nex1) [https://docs.tosspayments.com/llms.txt](https://docs.tosspayments.com/llms.txt) => { \"link\": \"https://docs.tosspayments.com/llms.txt\" }\nex2) [SDK 링크](/sdk/v2/js) => { \"link\": \"/sdk/v2/js\" }\nResponse\nMCP 서버 내부에서 채번한 unique 한 id 와 제목, 문서 설명 정보를 반환합니다.\n1 [Android, iOS 웹뷰에서 딥링크 열기] 각 딥링크 유형의 특징과 차이점을 자세히 알아보고, Android와 iOS 웹뷰에서 딥링크로 국내 카드앱·은행앱으로 이동하는 예시를 살펴볼게요.\n2 [Basic 인증과 Bearer 인증의 모든 것] 비밀번호로 이메일 계정의 권한을 확인하는 것 처럼, HTTP 인증으로 서버에 접근하는 클라이언트의 권한을 확인해요.\n...\n\n\ndocument-by-id\nMCP 서버 내부에서 채번한 ID를 기반으로 문서를 조회하는 도구입니다. get-keywords, documents-by-keywords, documents-by-link 도구를 사용하여 사용자 질의에 맞는 문서를 찾는 경우 해당 도구로 문서를 조회합니다.\n내부 동작 코드\nexport class TossPaymentDocsRepository {\n constructor(private readonly documents: TossPaymentsDocument[]) {}\n \n ...\n \n\tasync findOneById(id: number) {\n return notNull(this.documents[id]);\n }\n}\nDescription\n문서의 원본 ID 로 해당 문서의 전체 내용을 조회합니다.\nResponse\n***\n\ntitle: 예제로 이해하는 async/await 문법\ndescription: 오늘은 Promise의 단점을 알아보고, async/await 문법으로 어떻게 비동기 작업을 더 효율적으로 처리할 수 있는지 토스페이먼츠 결제위젯 예시로 자세히 살펴볼게요.\nkeyword: Promise, 프로미스, async, await, 비동기 작업, 결제 요청, 에러 처리\npublishedAt: 2023-10-10\nthumbnailSrc: https://static.toss.im/assets/payments/contents/paymetns-await-thumb.jpg\n--------------------------------------------------------------------------------------\n\n# 예제로 이해하는 async/await 문법\n\n2023년 10월 10일 ・ 읽는 시간 9분\n\n![async/await 문법 메인 이미지](https://static.toss.im/assets/payments/contents/paymetns-await-thumb.jpg)\n\n[지난 포스트](/blog/using-promises)에서는 콜백 함수 대신 Promise로 비동기 작업을 깔끔하게 처리하는 방법을 알아봤어요. 근데 Promise에도 콜백 함수와 비슷한 단점이 있어요. 오늘은 Promise의 단점을 알아보고, `async/await` 문법으로 어떻게 비동기 작업을 더 효율적으로 처리할 수 있는지 [토스페이먼츠 결제위젯](/guides/payment-widget/overview) 예시로 자세히 살펴볼게요.\n\n...\n\n결과 및 후기\n첫 번째 버전은 사전에 정의된 키워드를 기반으로 문서를 검색하는 방식이었습니다. 하지만 실제 운영을 해보니 AI 모델이 자꾸 엉뚱한 결과(Hallucination)를 내거나, 중요한 정보를 놓치는 경우가 많았어요. LLM의 호출 빈도도 증가했죠.\n문서별 길이가 천차만별이고, 길이가 긴 것은 5,000 라인이 넘어간다는 점이 원인으로 추측되었어요. 그런 문서들을 LLM이 여러 번 질의하면서 Checkpoint를 만들거나 대화내용을 요약하는 과정에서 중요한 정보들이 유실되는 현상으로 보여졌습니다. 때문에 새로운 방법을 고민해야했고 우리의 친구 Gemini, GPT와 이야기하며 다른 방법을 탐구했어요.\n\n두번째 버전\nGemini와 많은 대담을 나누다가 BM25라는 키워드를 확인했고, 해당 방식으로 변경해보기로 했어요.\n\nBM25는 Best Matching 25의 약자로, 확률적 정보 검색 모델인 Okapi BM25에서 유래했습니다. 이 모델은 특정 문서가 주어진 질의에 얼마나 관련이 있는지를 측정하는 방식으로 작동합니다.\n기본 개념\n문서에 등장한 질의어(Query term)의 빈도가 높을수록 관련성이 높다고 판단\n하지만 너무 자주 등장하는 단어는 가중치를 낮춤(IDF: 역문서 빈도)\n문서 길이에 따라 빈도의 영향을 보정함\n\n사용사례\n검색엔진: 사용자의 질의에 가장 관련 있는 문서 또는 웹페이지를 정렬\n문서 추천 시스템: 비슷한 내용을 가진 문서 간 유사도 측정\nRAG(Retrieval-Augmented Generation): LLM에 문서를 제공하기 위한 사전 필터링 단계\n\nBM25 사용하기\nJavascript에는 Python처럼 잘 구현된 BM25가 없어서, GPT의 도움을 받아 빠르게 만들어 볼 수 있었습니다. 하지만 해당 코드를 바로 사용할 수 없었는데요, 이유는 한국어의 특징 때문이었어요.\nGPT표 BM25\ntype DocumentTokens = string[];\n\nclass BM25 {\n private corpus: DocumentTokens[];\n private docCount: number;\n private docLengths: number[];\n private avgdl: number;\n private termDocFreqs: Map;\n private k1: number;\n private b: number;\n\n constructor(docs: string[], k1: number = 1.5, b: number = 0.75) {\n this.k1 = k1;\n this.b = b;\n this.corpus = docs.map(this.tokenize);\n this.docCount = this.corpus.length;\n this.docLengths = this.corpus.map(doc => doc.length);\n this.avgdl = this.docLengths.reduce((a, b) => a + b, 0) / this.docCount;\n this.termDocFreqs = this.calculateDocFrequencies();\n }\n\n private tokenize(text: string): DocumentTokens {\n return text.toLowerCase().match(/\\b\\w+\\b/g) || [];\n }\n\n private calculateDocFrequencies(): Map {\n const dfMap = new Map();\n for (const doc of this.corpus) {\n const uniqueTerms = new Set(doc);\n for (const term of uniqueTerms) {\n dfMap.set(term, (dfMap.get(term) || 0) + 1);\n }\n }\n return dfMap;\n }\n\n private idf(term: string): number {\n const df = this.termDocFreqs.get(term) || 0;\n return Math.log(1 + (this.docCount - df + 0.5) / (df + 0.5));\n }\n\n private termFrequency(term: string, doc: DocumentTokens): number {\n return doc.reduce((count, t) => (t === term ? count + 1 : count), 0);\n }\n\n public score(query: string, docIndex: number): number {\n const tokens = this.tokenize(query);\n const doc = this.corpus[docIndex];\n const dl = doc.length;\n\n let score = 0;\n for (const term of tokens) {\n const tf = this.termFrequency(term, doc);\n const idf = this.idf(term);\n const denom = tf + this.k1 * (1 - this.b + this.b * (dl / this.avgdl));\n score += idf * ((tf * (this.k1 + 1)) / denom);\n }\n return score;\n }\n\n public rank(query: string): { index: number; score: number }[] {\n return this.corpus.map((_, i) => ({\n index: i,\n score: this.score(query, i),\n })).sort((a, b) => b.score - a.score);\n }\n}\n\n예를 들어 다음 문장을 살펴 보겠습니다.\n\"BM25는 정보 검색에 사용되는 랭킹 함수입니다.\"\n영어식으로 토큰화하면 아래와 같은 결과가 나옵니다.\n[\"bm25는\", \"정보\", \"검색에\", \"사용되는\", \"랭킹\", \"함수입니다\"]\n\n발생한 문제\n의미 단위로 잘게 나눠지지 않음\n조사(는, 에), 어미(는, 다) 등이 그대로 포함되어 중복되고 불필요한 토큰이 많아짐\n같은 의미의 문장도 표현에 따라 일치하지 않음\n\n한국어 문장을 일관성 있고 의미 있게 토큰화하기 위해서는 형태소 분석 라이브러리가 필요했어요. 그러나 형태소 분석 라이브러리는 Java나 C와 같은 추가적인 환경 설정을 요구하기 때문에, 이러한 외부 의존성들이 로컬 MCP의 사용성을 저하시킬 수 있다고 판단하여 배제하였습니다. 다행히도 이 문제는 보다 간단한 방식으로 해결이 가능했어요.\nMCP 실행 환경에서는 모든 선택의 주체가 LLM입니다. 어떤 도구를 사용할지, 그리고 해당 도구를 어떤 파라미터로 실행할지는 전부 LLM이 결정하며, 사용자는 오직 도구 호출 여부만 선택하면 됩니다. 사용자의 질의를 LLM을 통해 유의미한 형태로 토큰화하고, 이 토큰화 된 질의에 정규식을 적용하여 매번 BM25 점수를 계산하면, 질문과 유사한 문서들을 효과적으로 색인할 수 있습니다.\n하지만 이 방법만으로 모든 문제가 해결되는 것은 아닙니다. 한국어 기반 문서에서 BM25를 적용하는 아이디어는 명확히 떠올렸지만, 본질적인 문제는 문서의 크기가 크다는 점이에요. 따라서 문서를 유의미한 크기의 청크(Chunk)로 잘라내는 작업이 추가로 필요했습니다.\n\n문서별 의미있는 Chunk 만들기\n청크(Chunk)를 너무 세분화하는 경우 중요한 정보가 유실될 수 있으므로, 마크다운 Header (#, ##)를 기준으로 문서를 자른 다음 BM25를 기반으로 점수를 계산하도록 개선하였습니다.\n\n마크다운을 파싱할 수 있는 라이브러리는 다양하지만, 저는 unist-util-visit, remark-parse, unified 세 가지 라이브러리를 활용하여 마크다운을 청크로 변환했습니다.\n\nunified 와 remark-parse 를 통해 markdown 을 분석하여 AST 트리로 변환합니다. \nconst tree = unified().use(remarkParse).parse(markdown);\n그 다음 unist-util-visit 을 사용하여 tree 를 순회합니다.\nvisit(tree, (node) => {\n if (node.type === \"heading\" && node.depth <= 2) {\n chunks.push(...)\n }\n ...\n});\n위의 과정을 거쳐서 각 마크다운 별로 header(#, ##)를 기준으로 문서를 자를 수 있습니다. \n\n마지막으로, 청크의 크기가 너무 작으면 유의미한 정보가 유실되거나 무의미한 데이터가 될 수 있으므로 일정 크기 이하의 청크는 병합하는 작업도 진행합니다.\n\nexport function joinShortChunks(chunks: string[], minWords = 30): string[] {\n const result: string[] = [];\n\n let buffer = \"\";\n let bufferCount = 0;\n\n for (const chunk of chunks) {\n const wc = chunk.split(/\\s+/).length;\n if (wc < minWords) {\n buffer += (buffer ? \"\\n\\n\" : \"\") + chunk;\n bufferCount += wc;\n continue;\n }\n\n if (buffer) {\n result.push(buffer.trim());\n buffer = \"\";\n bufferCount = 0;\n }\n\n result.push(chunk.trim());\n }\n\n if (buffer) {\n result.push(buffer.trim());\n }\n\n return result;\n}\n\nBM25에 정규식 및 청크 문서 적용하기 \n이제 준비는 끝났습니다. 청크를 관리하는 Document 클래스와 유저가 입력한 키워드를 정규식으로 변환하여 점수를 계산하는 Calculator 를 준비합니다.\nexport class TossPaymentsDocument {\n private readonly chunks: DocumentChunk[] = [];\n\n constructor(\n private readonly keywordSet: Set,\n private readonly remoteMarkdownDocument: RemoteMarkdownDocument,\n private readonly _version: string | undefined,\n public readonly id: number\n ) {\n remoteMarkdownDocument.chunks.forEach((chunk, index) => {\n this.chunks.push({\n id: this.id,\n chunkId: this.id * 1000 + index,\n originTitle: remoteMarkdownDocument.metadata.title,\n text: chunk,\n wordCount: chunk.split(/\\s+/).length,\n });\n });\n }\n\n getChunkWithWindow(chunkId: number, windowSize: number): DocumentChunk[] {\n const chunkIndex = this.chunks.findIndex(\n (chunk) => chunk.chunkId === chunkId\n );\n if (chunkIndex === -1) {\n return [];\n }\n\n const start = Math.max(0, chunkIndex - windowSize);\n const end = Math.min(this.chunks.length, chunkIndex + windowSize + 1);\n\n return this.chunks.slice(start, end);\n }\n\n getChunks(): DocumentChunk[] {\n return this.chunks;\n }\n\n get content(): string {\n return this.remoteMarkdownDocument.markdown;\n }\n\n get title() {\n return this.remoteMarkdownDocument.metadata.title;\n }\n\n get version(): string | undefined {\n return this._version;\n }\n\n get description() {\n return this.remoteMarkdownDocument.metadata.description;\n }\n\n toString() {\n return this.remoteMarkdownDocument.markdown;\n }\n\n toJSON() {\n return {\n version: this.version,\n id: this.id,\n title: this.title,\n link: this.remoteMarkdownDocument.link,\n description: this.description,\n keywords: Array.from(this.keywordSet),\n };\n }\n}\n\nexport class TossPaymentsBM25Calculator {\n private readonly allChunks: DocumentChunk[];\n pri","isDisplayingFeedback":false,"quizzes":[],"opinionForm":null,"viewCount":99714},{"id":37627,"updatedTime":"2025-08-28T03:01:44+09:00","createdTime":"2025-06-18T20:22:06+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"에러 0%, MSA에서의 Enum 관리 전략","subtitle":"토스뱅크 여신의 발전하는 MSA에서 Enum을 안전하게 사용하는 노하우를 알려드립니다.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/illusts-content/img-cover-techblog-server.jpg","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts-content/img-cover-techblog-server.jpg","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"msa-enum","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-06-18T20:30:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":37627,"title":null,"description":"안녕하세요, 토스뱅크 Server Developer 김인회 · 이준영입니다.토스뱅크는 다른 은행과 달리 시스템을 MSA(Microservice Architecture)로 구축해 빠른 개발과 배포 속도를 누리고 있습니다. 하지만 \"은탄환은 없다\"는 말처럼, MSA는 다양한 복잡함을 수반했...","urlSlug":"msa-enum","primaryKeyword":{"id":52949,"content":"Enum","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":44257,"content":"MSA","wordType":"SEO_KEYWORD"},{"id":52951,"content":"Server","wordType":"SEO_KEYWORD"},{"id":52953,"content":"kotlin","wordType":"SEO_KEYWORD"},{"id":52955,"content":"java","wordType":"SEO_KEYWORD"}],"tags":[{"id":41784,"content":"Server","wordType":"TAG"},{"id":52943,"content":"MSA","wordType":"TAG"},{"id":52945,"content":"Enum","wordType":"TAG"},{"id":52947,"content":"Kotlin","wordType":"TAG"}]},"openGraph":{"title":"에러 0%, MSA에서의 Enum 관리 전략","description":"안녕하세요, 토스뱅크 Server Developer 김인회 · 이준영입니다.토스뱅크는 다른 은행과 달리 시스템을 MSA(Microservice Architecture)로 구축해 빠른 개발과 배포 속도를 누리고 있습니다. 하지만 \"은탄환은 없다\"는 말처럼, MSA는 다양한 복잡함을 수반했...","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/illusts-content/img-cover-techblog-server.jpg","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2573,"name":"김인회/이준영","slug":null,"shortDescription":null,"description":null,"imageUrl":null,"url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, 토스뱅크 Server Developer 김인회 · 이준영입니다.\n토스뱅크는 다른 은행과 달리 시스템을 MSA(Microservice Architecture)로 구축해 빠른 개발과 배포 속도를 누리고 있습니다. 하지만 \"은탄환은 없다\"는 말처럼, MSA는 다양한 복잡함을 수반했는데요. 그중 하나가 바로 Enum","fullDescription":"안녕하세요, 토스뱅크 Server Developer 김인회 · 이준영입니다.\n토스뱅크는 다른 은행과 달리 시스템을 MSA(Microservice Architecture)로 구축해 빠른 개발과 배포 속도를 누리고 있습니다. 하지만 \"은탄환은 없다\"는 말처럼, MSA는 다양한 복잡함을 수반했는데요. 그중 하나가 바로 Enum입니다.\n이번 글에서는 MSA 환경에서 Enum이 왜 문제가 될 수 있는지, 그리고 토스뱅크는 이를 어떻게 해결했는지에 대해 소개해 드리려고 합니다.\n\nMSA에서는 독이 될 수 있는 Enum\nEnum은 타입 안정성, 컴파일 타임 체크, IDE의 자동완성 등의 장점이 있어서 Java 혹은 Kotlin을 다뤄본 개발자라면 자주 사용하는 도구일 것 입니다.\n하지만 MSA환경에서는 이러한 Enum이 자칫 독이 될 수도 있는데요.\nMSA에서는 하나의 Enum을 각 서버끼리 공유할 때 정의되지 않은 Enum 값이 넘어오면 Deserialize 에러가 발생합니다.\n\n\n많게는 1년에 한두번씩 꾸준히 발생하는 이 문제는, 단순히 휴먼 에러라고 치부하기에는 너무 빈번하고 치명적이에요. 담당자가 바뀌거나, 서비스가 확장되거나, 새로운 Enum 값이 추가되는 순간 다시 문제가 발생하기 시작했고 토스뱅크 또한 예외는 아니었습니다. \n발전하는 MSA 속에서 Enum 관리가 점점 어려워지기 시작했고 결국 사람의 주의가 아닌 시스템적으로 이 문제를 예방하고 관리할 수 있는 방법이 필요해지기 시작했습니다.\n\n제공자와 소비자\nMSA에서 Enum 문제가 복잡해지는 이유 중 하나는 통신 주체에 따라 기대하는 동작이 다르기 때문입니다. \n그래서 저희는 요청 주체 기준으로 Enum 사용을 '제공자'와 '소비자'로 나누었고 각각의 Use Case에 맞는 전략을 수립했습니다.\n\n1. 클라이언트(소비자) → 서버(제공자): 요청을 수신하는 입장에서는 오류가 명확해야 한다.\n클라이언트가 Enum 값을 요청으로 전달하고, 서버가 이를 파싱해 처리하는 구조에서 서버는 Enum 값의 의미를 정확히 이해하고 처리해야 하므로, 정의되지 않은 값을 받을 경우 즉시 에러를 반환하는 것이 타당합니다. \n예를 들어 \"UNKNOWN\"으로 처리해 흐름을 이어가면, 의도하지 않은 상태로 비즈니스 로직이 흘러갈 수 있고, 데이터 무결성이 훼손될 우려가 있습니다.\n따라서 이 경우에는 Enum 값을 엄격하게 검증하고, 알 수 없는 값은 400 Bad Request 등의 클라이언트 오류로 응답하는 것이 바람직합니다.\n\n2. 서버(제공자) → 클라이언트(소비자) : 처리는 소비자의 선택에 맡긴다\n반대로 서버가 Enum 값을 응답으로 보내고, 클라이언트가 이를 파싱하는 구조에서는 상황이 달라집니다. 서버가 Enum을 확장하여 새로운 값을 보내더라도, 클라이언트는 그 값을 아직 모를 수 있어요. 이때는 클라이언트 쪽에서 어떻게 대응할지를 선택할 수 있어야 합니다. \n예를 들어,\n알 수 없는 값이면 경고를 띄우고 무시한다\nfallback 동작으로 \"UNKNOWN\" 또는 \"기타\"로 처리한다\n오류를 발생시켜 사용자에게 명시적으로 알린다\n이처럼 소비자가 상황에 맞게 처리 전략을 선택할 수 있도록 열려 있는 구조가 필요합니다.\nKafka 소비자나 이벤트 핸들러 등 외부로부터 Enum을 수신하는 구조에서도 마찬가지입니다. \n\n이렇게, 각 Use Case 별 전략 수립 과정을 거쳐서 저희는 Enum deserialize 오류로부터 자유로워질 수 있는 아래 세 가지 해결책을 도출했습니다.\n\nEnum을 선택적으로 deserialize하기 - EnumString\nEnumString 전파하기 - ArchUnit\nEnum 배포 의존성 끊기 - Meta Expose\n이번 글에서는 이 세 가지 해결책을 통해 어떻게 Enum deserialize 오류를 극복했는지 자세히 살펴보겠습니다.\n1. Enum을 선택적으로 deserialize하기 - EnumString\n알지 못하는 Enum 값이 들어왔을 때 이를 역직렬화(deserialize)하는 방안을 고민하며, 처음에는 다음과 같은 방법들을 떠올렸어요.\n\n@JsonEnumDefaultValue 혹은 @JsonCreator 설정을 추가해서 입력과 일치하는 Enum이 없으면 기본값을 내려준다.\n@JsonCreator와 Property 를 사용해서 기본값을 반환할 Enum을 선택할 수 있게 한다.\n하지만 이러한 해결법들은 기본값을 내려주더라도 도메인 로직상 여전히 예기치 않은 버그가 발생할 수 있으며, 개발자가 의도한대로 동작을 완전히 제어하기 어렵다는 한계가 있었습니다.\n따라서 저희는 Enum 타입이 지닌 장점을 유지하면서도, 예상치 못한 값이 들어왔을 때 개발자가 직접 원하는 동작을 정의할 수 있는 유연한 접근법을 도입하기로 결정했어요.\n하지만, 단순히 String으로 처리하는 것으로는 이 같은 유연성을 만족시키기 어렵고 사용성에 제한을 두기도 어려웠기 때문에, 아래와 같은 사용성을 제공하는 전용 라이브러리를 제작하게 되었습니다.\n\n\n\nEnumString의 사용 예시를 코드로 보면 아래와 같은데요. 만약, EnumString이 아래와 같이 되어 있다고 가정하면,\nabstract class EnumString, T : EnumString>(\n @get:JsonValue\n override val value: String,\n) : DelegatedValue(value), Comparable> {\n\n \n \n open fun toEnumOrElse(defaultValueSupplier: () -> E): E = toEnumOrNull() ?: defaultValueSupplier()\n \n open fun toEnumOrThrow(exceptionSupplier: () -> RuntimeException = { IllegalStateException(\"\\\"$value\\\" 에 해당하는 ${EnumName}을 찾을 수 없습니다. dependency version을 체크해주세요.\") }): E = toEnumOrNull()\n ?: throw exceptionSupplier()\n \n open fun toEnumOrNull(): E? = EnumFinder.findByNameOrNull(value)\n \n companion object {\n val CONSTRUCTOR_CACHE = ConcurrentHashMap>, KCallable<*>>()\n inline fun , reified T : EnumString> E.toEnumString(): T {\n val constructor = CONSTRUCTOR_CACHE.computeIfAbsent(T::class) {\n ...\n }\n return constructor.call(this.name) as T\n }\n }\n}\n\nEnumString을 적용하려는 Enum은 아래처럼 간단히 EnumString 인터페이스만 구현하면 됩니다.\nEnum class Animal {\n\n\tDOG,\n\tCAT,\n\tRABBIT,\n\t;\t\n}\n\nclass AnimalString private constructor(\n\toverride val value: String\n) : EnumString(...)\n\n이렇게 정의된 다음에는, DTO에서 Enum을 EnumString 타입으로 선언하고 나서 필요에 따라 선택적으로 역직렬화 결과를 처리할 수 있게 되는데요. \ndata class Foo(\n val animal: AnimalString,\n)\n\n// 아래와 같이 선택적으로 Enum을 deserialize 할 수 있습니다. \nfun helloWorld() {\n\tfoo.animal.toEnumOrElse { throw IllegalArgumentException(\"역직렬화에 실패했어요.\") }\n\t\n\tfoo.animal.toEnumOrElse { return@toEnumOrElse Animal.DOG }\n\t\n\t// 혹은 필요에 따라 아래와 같은 편의 제공 메소드를 활용할 수도 있습니다.\n\tfoo.animal.toEnumOrThrow()\n\tfoo.animal.toEnumOrNull()\n}\n사용자는 상황에 따라 세 가지 메소드를 유연하게 선택해 사용할 수 있습니다.\ntoEnumOrNull / toEnumOrElse: 무시해도 괜찮은 경우에는 null 또는 지정된 기본값을 반환하고,\ntoEnumOrThrow: 무시하면 안 되고 반드시 함께 버전업 되어야 하는 경우에는 예외를 발생시킵니다.\n이처럼 EnumString을 도입하면서 불명확한 Enum 입력에 대해 “예외 발생” 또는 “기본값 할당” 등 원하는 동작을 직접 정의할 수 있게 되었고, 결과적으로 Deserialize 과정에서 발생할 수 있는 오류를 안전하게 제어할 수 있게 되었습니다.\n\n2. EnumString 전파하기 - ArchUnit\n아무리 좋은 해결책 이더라도, 전파되지 않으면 무용지물이죠. 특히, 새로 합류한 구성원이 과거 문제를 잘 모른 채 기존처럼 Enum을 사용할 가능성도 고려해야 했어요. 그래서, 저희는 제공자 → 소비자 패턴에서 EnumString 사용을 시스템적으로 강제할 수 있는 방법을 찾기 시작했고 그 결과 ArchUnit을 찾게 되었습니다.\n\nArchUnit은, 패키지와 클래스간의 의존성을 테스트 해주는 오픈소스 라이브러리 도구로 저희만의 커스텀 룰을 만들어서 제공하면 제공자 → 소비자 패턴에서 EnumString을 막을 수 있었습니다.\n그래서 저희는 공용 레포에 대해 ArchUnit으로 규칙을 만들고, 컨슈머 코드에서 Enum 사용을 감지해 빌드 시점에 실패하도록 설정했습니다. 덕분에 새로운 구성원도 EnumString을 자연스럽게 사용하게 만들 수 있었습니다.\n\n\n\n\n3. Enum 배포의존성 끊기 - Meta Expose\n위에서 소개한 EnumString 도입 이후, 서비스는 이전보다 훨씬 안정적으로 운영될 수 있게 되었습니다. 특히 버전과 무관하게 무시 가능한 Enum 값들에 대해서는 문제가 거의 발생하지 않게 되었죠.\n하지만, 모든 Enum이 그렇게 유연할 수는 없었습니다. 어떤 Enum은 반드시 서비스 간에 함께 버전업이 되어야만 의미가 유지되며, 그렇지 않으면 여전히 오류가 발생할 수 있습니다.\n예를 들어, 소비자(Consumer)라고 하더라도 \"정의되지 않은 Enum 값을 받으면 도메인 로직이 깨지므로 오류를 발생시켜야 하는\" 경우도 있었고, 제공자(Publisher) 입장에서도 Enum이 갱신되지 않은 소비자에게 메시지를 전송하면 실패가 발생하는 구조는 여전히 유효했습니다.\n이를 해결하기 위해 저희는 Enum의 버전 동기화 상태를 관찰(Observe)하고 감지할 수 있는 시스템, Meta-Expose를 설계하고 도입하게 되었습니다.\n\nMeta Expose의 핵심 구성과 동작 방식\nMeta Expose의 구조를 그려보면 아래와 같은데요. 중앙의 Meta-Expose-Hub에서 Enum을 사용하는 모든 서버를 watch하고 있다가 버전이 올라가지 않은 서버를 자동으로 감지해 어드민과 모니터링 도구로 알림을 주게 됩니다.\n\n자동 노출된 Enum API\nMeta-Expose 라이브러리를 사용하는 서비스는 자신의 Enum 정의값을 자동으로 외부 API로 노출합니다.\n이 API는 서비스 코드에 추가 작업 없이 자동 구성(auto config)됩니다.\n중앙 Hub에서의 정합성 검증\nMeta-Expose-Hub는 ServiceDiscovery를 통해 Enum API를 가진 서비스를 식별하고, 주기적으로 호출하여 Enum 정의값을 수집합니다.\n이를 기준 Enum과 비교해 정의의 일관성을 검증합니다.\n동적으로 서비스 식별\nServiceDiscovery는 Meta-Expose 의존성을 가진 서비스만을 식별해 관리합니다.\n신규 서비스도 자동으로 포함되어, 누락 없이 전체 시스템을 커버할 수 있습니다.\nGrafana를 통한 모니터링\n검증 결과는 Prometheus에 지표(metric)로 수집되고, Grafana 대시보드를 통해 실시간으로 시각화됩니다.\n특정 Enum 정의가 불일치하거나 누락된 서비스가 있는 경우 대시보드에서 바로 확인할 수 있으며, 알림 연동도 가능합니다.\n\n\n이 시스템을 통해 저희는 다음과 같은 효과를 얻을 수 있게 되었고, 마침내 Enum deserialize 에러에서 자유로워질 수 있었습니다.\nEnum 변경 시, 모든 관련 서비스가 실제로 버전업 되었는지를 눈으로 확인 가능합니다.\n신규 Enum 추가 이후 배포 누락 서비스가 있다면 빠르게 감지하여 운영환경에서 발생할 수 있는 리스크를 사전에 제거할 수 있었습니다.\n신규 구성원이 Enum 정의 방식에 익숙하지 않더라도 자동 검증과 시각화 덕분에 실수를 방지할 수 있었습니다.\n마치며\n실수를 완전히 막을 순 없지만, 이를 문제로 확산되지 않도록 시스템 차원에서 방어하는 것은 개발자의 몫입니다. 그래서 저희는 예측 가능한 구조와 자동화된 감시 체계를 통해 오류를 사전에 차단하고자 했어요. 이러한 노력 덕분에, 수백 번의 배포와 확장되는 MSA 환경 속에서도 단 한 번의 Enum 이슈 없이 안정적인 서비스를 운영하는 성과를 얻을 수 있었습니다.\n토스뱅크는 고객의 자산을 직접 다루는 은행 서비스 특성상, 1년에 한 번 발생할 수 있는 작은 버그라도 결코 가볍게 넘기지 않습니다. 성능만큼 안정성이 중요한 은행 도메인에서, 구조적으로 실수를 방지하고 예측 가능한 시스템을 함께 설계해 나가고 싶다면, 토스뱅크에 합류해 주세요.\n\n","isDisplayingFeedback":false,"quizzes":[],"opinionForm":null,"viewCount":34506},{"id":37487,"updatedTime":"2025-08-28T03:55:35+09:00","createdTime":"2025-06-13T16:12:55+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"신용대출 찾기 서비스 제휴사 mock 서버 개발기 #1","subtitle":"대출 연동 테스트의 안정성과 효율성을 극대화하는 mock 서버 개발기를 공유합니다.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/illusts-content/0613_techthumb.png","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts-content/0613_techthumb.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"credit-loan-partner-mock-server","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-06-13T17:22:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":37487,"title":null,"description":"안녕하세요, 토스 신용대출 찾기 서비스 팀 Server Developer 류경린입니다.신용대출 찾기 서비스는 다양한 제휴사의 대출 상품을 연동하여, 고객이 보다 편리하게 대출 상품을 탐색하고 신청할 수 있도록 돕는 서비스입니다. 이번 글에서는 신규 제휴사 연동 이후 제휴사의 테스트 서버...","urlSlug":"credit-loan-partner-mock-server","primaryKeyword":{"id":52859,"content":"모의서버","wordType":"SEO_KEYWORD"},"relatedKeywords":[],"tags":[{"id":41784,"content":"Server","wordType":"TAG"}]},"openGraph":{"title":"신용대출 찾기 서비스 제휴사 mock 서버 개발기","description":"신용대출 찾기 서비스는 다양한 제휴사의 대출 상품을 연동하여, 고객이 보다 편리하게 대출 상품을 탐색하고 신청할 수 있도록 돕는 서비스입니다. 이번 글에서는 신규 제휴사 연동 이후 제휴사의 테스트 서버가 유효한 응답을 주지 않거나, 특정 케이스를 테스트하기 어려운 상황을 어떻게 해결했는지...","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/illusts-content/0613_techthumb.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2565,"name":"류경린","slug":null,"shortDescription":null,"description":null,"imageUrl":null,"url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":2,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, 토스 신용대출 찾기 서비스 팀 Server Developer 류경린입니다.\n신용대출 찾기 서비스는 다양한 제휴사의 대출 상품을 연동하여, 고객이 보다 편리하게 대출 상품을 탐색하고 신청할 수 있도록 돕는 서비스입니다. \n이번 글에서는 신규 제휴사 연동 이후 제휴사의 테스트 서버가 유효한 응답을 주지 않거나, ","fullDescription":"안녕하세요, 토스 신용대출 찾기 서비스 팀 Server Developer 류경린입니다.\n신용대출 찾기 서비스는 다양한 제휴사의 대출 상품을 연동하여, 고객이 보다 편리하게 대출 상품을 탐색하고 신청할 수 있도록 돕는 서비스입니다. \n이번 글에서는 신규 제휴사 연동 이후 제휴사의 테스트 서버가 유효한 응답을 주지 않거나, 특정 케이스를 테스트하기 어려운 상황을 어떻게 해결했는지, 그리고 이를 위해 설계한 mock 서버를 소개하고자 해요.\n\n배경\n신규 제휴사 연동 이후 다음과 같은 문제들이 반복적으로 발생했어요.\n제휴사 개발 서버의 불안정한 응답 혹은 장애\n특정 퍼널 또는 고객 조건에 맞는 테스트 데이터 확보의 어려움\n테스트 과정에서 실제 제휴사 서버로부터 유효한 응답을 받기 어려운 상황\n이러한 문제들은 QA 및 신규 기능 개발 효율을 떨어뜨릴 뿐 아니라, 서비스 출시 일정에도 영향을 주었습니다. 이를 해결하기 위해 사용자, 제휴사, 퍼널 단위로 정밀하게 동작을 제어할 수 있는 mock 서버를 설계했어요.\n\n용어 정리\n본격적인 설명에 앞서, 대출 도메인과 관련된 주요 용어를 간략히 정리할게요.\n제휴사: 은행, 저축은행, 보험사 등 대출 상품을 제공하는 금융기관\n가심사 조회: 고객 정보를 활용해 대출 금리, 한도 등을 간단히 확인하는 행위\n대출 신청: 가심사 결과를 바탕으로 고객이 특정 상품에 대해 대출을 신청하는 행위\n대출 실행: 제휴사가 고객 정보를 활용해 대출을 실행하고 자금을 입금하는 행위\n\n요구사항\n기능적 / 비기능적 요구사항은 아래와 같았어요.\n기능적 요구사항\n\n유저, 제휴사, 퍼널 단위로 mock 사용 여부를 설정할 수 있어야 한다.\n동기/비동기 응답 방식을 모두 지원해야 한다.\nrelay 서버 역할을 수행해야 한다.\n유저가 쉽게 설정할 수 있어야 한다.\n\n비기능적 요구사항\n\n기존 비즈니스 로직은 변경하지 않는다.\nmock 서버에서 로직을 처리하기 위해 필요한 값은 커스텀 헤더로 전달한다.\n토스 내 타 서비스에서도 mock 서버를 손쉽게 연동할 수 있는 유연한 구조를 제공한다.\n\n설계 및 구현\nmock 서버는 다음과 같은 구성요소로 설계되었습니다.\n\n커스텀 헤더 주입\n설정\n예약(비동기 응답 지원)\nmock 데이터 생성\nRelay 서버 역할\n메신저봇 연동\n유연한 연동 구조 제공\n\n1. 커스텀 헤더 주입\n신용대출 찾기 서비스는 mock 동작 여부나 mock 데이터 생성 시 필요한 유저 정보를 클라이언트 요청의 헤더를 통해 주입받습니다. 이렇게 하면 비즈니스 로직에는 전혀 영향을 주지 않고, 테스트를 유연하게 제어할 수 있어요.\n테스트 환경에서만 동작하도록 @Profile(\"dev\") 설정을 통해 관리하며, 실제 통신 로직(RestTemplate, WebClient)에서 헤더 주입이 이뤄집니다.\n\nRestTemplate\nRestTemplate에는 인터셉터를 통해 요청마다 헤더를 추가할 수 있어요. 아래는 유저 ID와 원장 ID를 주입하는 예시입니다.\n해당 인터셉터를 RestTemplate에 등록하면, 모든 제휴사 요청에 자동으로 헤더가 포함됩니다.\nclass MockServerHeaderInjectionInterceptor : ClientHttpRequestInterceptor {\n override fun intercept(\n request: HttpRequest,\n body: ByteArray,\n execution: ClientHttpRequestExecution,\n ): ClientHttpResponse {\n val headers = request.headers\n headers.add(MOCK_SERVER_HEADER_X_REQUEST_ID, \"ids\")\n headers.add(MOCK_SERVER_HEADER_X_USER_ID, \"userId\")\n\n return execution.execute(request, body)\n }\n}\n\nWebClient\nWebClient에서는 ExchangeFilterFunction을 활용해 헤더를 주입해요. 아래는 동일한 목적의 필터 예시입니다.\nWebClient 설정 시 이 필터를 .filter(addMockServerHeaderFilter())와 같이 등록해주면 돼요.\nprivate fun addMockServerHeaderFilter(): ExchangeFilterFunction {\n return ExchangeFilterFunction.ofRequestProcessor { clientRequest: ClientRequest ->\n val injectedHeaders = ClientRequest.from(clientRequest)\n .headers { headers: org.springframework.http.HttpHeaders ->\n headers.add(MOCK_SERVER_HEADER_X_REQUEST_ID, \"ids\")\n headers.add(MOCK_SERVER_HEADER_X_USER_ID, \"userId\")\n }\n .build()\n Mono.just(injectedHeaders)\n }\n}\n\n2. 설정\n모든 설정값은 DB 테이블에서 관리하여 유연성을 확보했어요.\npartner_metadata: 제휴사 메타데이터\n응답의 동기 / 비동기 방식 여부\n네트워크 설정\n암호화 여부 등\npartner_response: 퍼널별 mock 응답 데이터\nmock 데이터\n응답 결과 json layout 등\nuser_status: 유저별 mock 응답 사용 여부 및 응답 지연 설정\n콜백 을 N 초 후에 받을 것인지\n특정 퍼널 에 대해 어떤 mock 응답을 받을 것인지 등\n\n정의된 정보를 사용해 mock 응답 을 생성합니다.\nval key = Triple(companyId, funnelType, status)\n// 주어진 정보를 사용해 response 를 생성한다.\nval response = partnerResponseService.create(key, metadata, requests)\n\n3. 예약\nmock 서버에서는 실제 제휴사처럼 콜백 응답을 지연하여 전송하는 기능이 필요합니다. 이를 통해 비동기 응답을 테스트할 수 있도록 지원하며, 실제 서비스 환경을 더 현실감 있게 시뮬레이션할 수 있어요.\n예약은 다음과 같이 두 단계로 구성됩니다.\n\n1. 예약 등록\n가심사 조회나 대출 신청 API 호출 시점에, 예약 정보를 DB에 저장합니다.\n각 요청에 대해 몇 초 후 콜백을 호출할 지 결정되며, 이 설정은 유저 설정(user_status) 또는 제휴사 메타데이터(partner_metadata)에 정의된 값을 사용합니다.\n저장된 예약 정보는 schedule.executeTs 필드에 실행 시점을 기록합니다.\n\n2. 예약 실행\nmock 서버에서는 @Scheduled를 사용해 1분 단위로 주기적인 예약 조회 작업을 수행합니다.\n실행 시점(executeTs)이 지난 예약 건들을 조회한 후, ThreadPoolTaskScheduler를 사용해 콜백 API 요청을 실제로 전송합니다.\nprivate fun reserveInternal(schedule: ScheduleEntity, forceReserve: Boolean = false) {\n handlers\n .filter { it.canHandle(schedule) }\n .forEach { handler ->\n repository.save(schedule)\n if (forceReserve) {\n schedule.reserve()\n repository.save(schedule)\n scheduler.schedule(\n { submitTask(schedule, handler) },\n schedule.executeTs.atZone(ZoneId.systemDefault()).toInstant(),\n )\n return@forEach\n }\n\n lockExecutor.runOnce(\n lockKey = \"$LOCK_KEY_PREFIX${schedule.id}\",\n lockDuration = Duration.ofMinutes(1),\n ) {\n schedule.reserve()\n repository.save(schedule)\n scheduler.schedule(\n { submitTask(schedule, handler) },\n schedule.executeTs.atZone(ZoneId.systemDefault()).toInstant(),\n )\n }\n }\n }\n\n4. mock 데이터 생성\nmock 응답은 실제 제휴사 응답과 동일한 포맷으로 생성되어야 해요. 특히 상품명, 금리, 한도, 기간 등의 값은 토스 원장 데이터와 정합성 있게 주입되어야 하며, 이를 위해 다음과 같은 흐름으로 데이터를 생성합니다.\n\n1. 예약어 기반 mock 템플릿 정의\n각 제휴사별 응답 포맷에 따라 mock 템플릿을 사전에 정의합니다.\n이 템플릿은 \"{{amount}}\", \"{{productId}}\"와 같은 예약어를 포함해요.\n{\n \"amount\": \"{{amount}}\",\n \"period\": \"{{period}}\",\n \"interestRate\": \"{{interestRate}}\",\n \"productId\": \"{{productId}}\",\n \"id\": \"{{id}}\"\n}\n\n\n\n2. 예약어 치환\n응답 JSON 내의 예약어를 실제 원장 데이터로 치환합니다.\n이 때 JsonNode 객체를 순회하며 깊은 중첩 구조까지 치환되도록 설계했어요.\nfun replace(\n replaceParams: Map,\n node: JsonNode,\n): JsonNode {\n when {\n node.isObject -> {\n val objectNode = node as ObjectNode\n objectNode.fields().forEach { (key, value) ->\n replaceParams.forEach { (keyword, replaceKeyword) ->\n if (value.asText() == keyword) {\n objectNode.put(key, replaceKeyword)\n }\n }\n replace(replaceParams, value)\n }\n }\n node.isArray -> {\n val arrayNode = node as ArrayNode\n arrayNode.forEach { replace(replaceParams, it) }\n }\n node is Collection<*> -> {\n node.filterIsInstance()\n .forEach { replace(replaceParams, it) }\n }\n }\n return node\n}\n예를 들어, \"{{productId}}\"는 실제 상품명으로 \"{{amount}} 는 대출 한도로 치환됩니다.\n{\n \"amount\": \"10000000\",\n \"period\": \"12\",\n \"interestRate\": \"2.4\",\n \"productId\": \"OOO 자동차 담보 대출\",\n \"id\": \"{{id}}\"\n}\n\n3. 상품명 → 원장 아이디 매핑 처리\n각 원장에 매핑된 고유한 productId를 기반으로 다시 한 번 ID 매핑을 수행합니다.\nloan_product_id_property_names 필드를 통해 각 제휴사마다 어떤 필드명이 상품명인지를 메타데이터로 관리하고 있기 때문에, 이를 기준으로 정확한 치환이 가능해요.\nprivate fun replace(\n propertyNames: List,\n keyword: String,\n replaceKeywordByPropertyNames: Map,\n node: JsonNode,\n) {\n when {\n node.isObject -> {\n val objectNode = node as ObjectNode\n val propertyName = propertyNames.firstNotNullOfOrNull { objectNode.get(it)?.asText() }\n\n // objectNode.fields.value 가 ObjectNode 일 수 있기 때문에 반드시 objectNode 의 전체 field 를 순회한다.\n objectNode.fields().forEach { (key, value) ->\n if (value.asText() == keyword) {\n // keyword 를 templateValue 로 치환한다.\n val templateValue = replaceKeywordByPropertyNames[propertyName]!!\n objectNode.put(key, templateValue)\n }\n replace(propertyNames, keyword, replaceKeywordByPropertyNames, value)\n }\n }\n node is Collection<*> -> {\n node.filterIsInstance()\n .forEach { replace(propertyNames, keyword, replaceKeywordByPropertyNames, it) }\n }\n node.isArray -> {\n val arrayNode = node as ArrayNode\n arrayNode.forEach { replace(propertyNames, keyword, replaceKeywordByPropertyNames, it) }\n }\n }\n return\n}\n예를 들어, “OOO 자동차 담보 대출” 상품명 에 맞는 거래번호 123456789가 치환됩니다.\n{\n \"amount\": \"10000000\",\n \"period\": \"12\",\n \"interestRate\": \"2.4\",\n \"productId\": \"OOO 자동차 담보 대출\",\n \"id\": \"123456789\"\n}\n\n5. Relay 서버\nmock 서버 는 아래 2가지 상황에 대해 relay 서버 역할을 해야 해요.\n유저가 mock 응답 을 사용하지 않는 경우\n제휴사 에서 콜백 API 를 호출하는 경우\n\n유저가 mock 응답을 사용하지 않는 경우, 아래처럼 직접 제휴사 를 호출해 응답을 relay 합니다.\nif (userStatus?.getPartnerResponseStatus(type) != null) {\n return getMockResponse()\n}\nval response = callPartner()\n\n제휴사에서 콜백 API 를 호출하는 경우\n제휴사에서 토스로 콜백 API 를 호출 하는 경우, api gateway를 통해 해당 요청이 인입돼요.\napi gateway의 routing rule 을 신용대출 찾기 서버 에서 mock 서버로 수정해, mock 서버에서 콜백 API를 받고 이를 다시 신용대출 찾기 서버로 호출합니다.\n\n6. 메신저봇 을 활용한 mock 설정\n팀내에서 사용하고 있는 메신저봇에 mock 서버 설정 및 설정을 확인할 수 있는 기능을 추가합니다.\n\n\n현재 제휴사, 퍼널 별 mock 설정 확인 버튼을 클릭해 현재 어떤 제휴사의 어떤 퍼널 에 대해 mock 데이터를 사용하고 있는지를 쉽게 알 수 있어요.\n\n\n\n제휴사, 퍼널 mock 설정 버튼을 클릭해 특정 제휴사 의 어떤 퍼널에 대해 mock 데이터를 사용할지 쉽게 설정할 수 있습니다.\n\n\n7. 유연한 연동 구조 제공\nmock 서버는 토스 내 다양한 제휴사 연동 서비스들이 손쉽게 통합 및 활용할 수 있도록 확장 가능하고 유연한 아키텍처를 제공해요. 제휴사 연동 서비스는 검색, 신청, 취소, 상태 조회의 크게 네 가지 기능을 수행합니다.\n\n모듈 구조\nmock 서버는 모듈화된 구조를 통해 서비스별로 손쉽게 연동할 수 있도록 설계되었어요. 각 서비스에서 mock 서버를 연동할 경우, 해당 서비스 전용 모듈만 추가하면 되는 구조입니다.\nmock-server-api : 각 서비스로부터 요청을 수신하는 API 모듈\nmock-server-base : 콜백, 치환 기능 등 모든 서비스에서 공통적으로 사용할 수 있는 기능 및 추상화된 Handler를 제공하는 기반 모듈\nmock-server-serviceA : 특정 서비스의 비즈니스 로직을 담은 모듈\nmock-server-serviceA-admin : 특정 서비스의 어드민 기능을 포함한 모듈\n\nMulti DataSource 지원\n서비스 모듈마다 별도의 데이터 소스(DataSource)를 사용해야 하는 경우가 있어, Spring 기반에서 Multi DataSource를 구성할 수 있는 세 가지 방식 중 아래와 같은 특징을 고려해 Class 기반 정의 방식을 채택했어.\nbase package 기준 정의\nannotation 기반 정의\nclass 기반 정의 ✅\n\n채택 사유:\n1. Repository 상속 구조에 불편함\nadmin 모듈은 어드민 특화 쿼리를 별도로 정의합니다.\n동시에 기존 서비스 모듈의 공통 Repository 기능도 재사용해야 합니다.\n따라서 admin 모듈의 repository 클래스는 서비스 모듈의 repository를 상속하는 구조입니다.\n2. 어노테이션 중복 선언 문제\n어노테이션 기반(@ServiceARepository) 으로 설정할 경우, 서비스 모듈의 repository 클래스와 어드민 모듈의 repository 클래스 양쪽에 동일한 어노테이션을 선언해야 하는 번거로움이 발생합니다.\n이는 유지보수 시 의도치 않은 설정 누락 혹은 중복을 유발할 수 있고, 설정 관리가 복잡해집니다.\n3. 패키지 구조의 자율성 확보\n모듈 단위로 동일한 패키지 구조를 사용할 수 있기 때문에 base package 스캔 방식 역시 적용이 어렵습니다.\n\n프로퍼티 설정 전략\n각 모듈에서 필요한 설정은 모듈 내부의 application-{service}.properties 파일을 통해 정의해요.\n기존에는 mock-server-base의 application.properties에 모든 설정을 통합할 수도 있었지만, 각 설정이 어떤 서비스에 영향을 미치는지를 명확히 구분하고 관리하기 어려운 점을 고려하여 모듈별로 분리하는 방식을 선택했어요.\n최종적으로는 base 모듈의 application.properties에서 spring-cloud-config 및 각 서비스의 설정 파일(application-{service}.properties)을 import하여, 모든 프로퍼티를 통합적으로 로딩할 수 있도록 구성합니다.\n\n마치며\n대외 기관과의 연동을 다루는 많은 회사들이 저희와 유사한 어려움을 겪고 있을 거라 생각해요.\n토스의 신용대출 찾기 서비스 팀은 mock 서버와 relay 기능을 결합한 테스트 환경을 누구나 쉽게 이용할 수 있게 구축함으로써, 테스트 효율성과 신뢰성을 모두 확보할 수 있었습니다.\n이 글이 유사한 문제를 고민하고 있는 개발자분들께 실질적인 도움이 되었으면 좋겠습니다. 감사합니다.\n","isDisplayingFeedback":false,"quizzes":[],"opinionForm":null,"viewCount":10816},{"id":37229,"updatedTime":"2025-08-28T00:39:49+09:00","createdTime":"2025-06-07T07:25:16+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"토스 프론트엔드 챕터가 오픈소스를 통해 꿈꾸는 미래","subtitle":"토스 프론트엔드 챕터의 오픈소스 위원회를 소개해요.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/photos/CM2_1805.JPG","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"toss-oss-committee","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-06-05T16:30:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":37229,"title":null,"description":"이 질문은 토스 프론트엔드 챕터의 몇몇 개발자들이 아주 가볍게 던졌던 의문이었어요. 어떻게 보면 가볍게 넘길 수 있는 질문이었지만, 곱씹을수록 새로운 의문이 계속 생겨났습니다.정말 그럴 수밖에 없는 걸까? 우리는, 한국의 개발자들은, 그렇게 만들 수 없는 사람들일까? 실리콘밸리의 개발자...","urlSlug":"toss-oss-committee","primaryKeyword":{"id":44617,"content":"오픈소스","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":37498,"content":"프론트엔드","wordType":"SEO_KEYWORD"},{"id":52631,"content":"es-toolkit","wordType":"SEO_KEYWORD"},{"id":52633,"content":"오픈소스위원회","wordType":"SEO_KEYWORD"}],"tags":[]},"openGraph":{"title":"토스 프론트엔드 챕터가 오픈소스를 통해 꿈꾸는 미래","description":"이 질문은 토스 프론트엔드 챕터의 몇몇 개발자들이 아주 가볍게 던졌던 의문이었어요. 어떻게 보면 가볍게 넘길 수 있는 질문이었지만, 곱씹을수록 새로운 의문이 계속 생겨났습니다.정말 그럴 수밖에 없는 걸까? 우리는, 한국의 개발자들은, 그렇게 만들 수 없는 사람들일까? 실리콘밸리의 개발자...","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/photos/CM2_1805.JPG","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2134,"name":"문동욱","slug":"evan-moon","shortDescription":null,"description":"거북이처럼 사는 프론트엔드 개발자","imageUrl":"https://static.toss.im/assets/toss-tech/profile.png","url":"https://evan-moon.github.io/","facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"“왜 대한민국에서는 lodash, react와 같이 세계적인 라이브러리가 나오지 않는걸까요?”\n\n이 질문은 토스 프론트엔드 챕터의 몇몇 개발자들이 아주 가볍게 던졌던 의문이었어요. 어떻게 보면 가볍게 넘길 수 있는 질문이었지만, 곱씹을수록 새로운 의문이 계속 생겨났습니다.\n정말 그럴 수밖에 없는 걸까? 우리는, 한국의 개","fullDescription":"“왜 대한민국에서는 lodash, react와 같이 세계적인 라이브러리가 나오지 않는걸까요?”\n\n이 질문은 토스 프론트엔드 챕터의 몇몇 개발자들이 아주 가볍게 던졌던 의문이었어요. 어떻게 보면 가볍게 넘길 수 있는 질문이었지만, 곱씹을수록 새로운 의문이 계속 생겨났습니다.\n정말 그럴 수밖에 없는 걸까? 우리는, 한국의 개발자들은, 그렇게 만들 수 없는 사람들일까? 실리콘밸리의 개발자와 우리가 정말 그렇게까지 다를까?\n우리는 정말 “기여자”가 아닌 “사용자”의 역할에만 머물러야 할까?\n결국 우리는 이 질문에 제대로 답해보기로 했습니다.\n\n물론 다른 뛰어난 개발자들도 해내지 못한 것을 우리가 할 수 있을까 하는 걱정도 들었지만, Execution Over Perfection이라는 코어밸류를 떠올리며, 정답보다 실행을, 완벽보다 작은 실험을 먼저 시작해보기로 했어요.\n그 첫 번째 실험이 바로 토스 프론트엔드 챕터의 오픈소스 위원회입니다.\n\n\n작은 실험을 가능하게 만든 구조\n우리가 만든 건 단지 라이브러리가 아니에요. 작은 시도들이 살아남을 수 있는 ‘판’을 만드는 실험이었습니다.\n\n마음을 움직인 건 숫자가 아니었어요\n처음 오픈소스 위원회라는 아이디어가 제안되었을 때는 챕터 동료들을 설득하고 참여시키기 위해 철저하게 비즈니스적 논리를 준비해갔던 기억이 납니다. 외부 개발자들이 기여하면 유지보수 리소스를 줄일 수 있고, 오픈된 코드가 신규 입사자의 온보딩 속도를 높여줄 수 있고, 오픈소스 자체가 우리 기술 브랜딩에 도움이 된다는 식으로요.\n그 논리 자체는 나쁘지 않았지만, 이야기를 조금 나누다보니 동료들의 마음을 진짜 움직인 건 그런 숫자가 아니었어요.\n“그냥… 대한민국에서도 세계적인 오픈소스가 등장하는 과정을 우리 손으로 한 번 만들어보고 싶어요.”\n“시장 전체에 선한 영향력을 줄 수 있다면, 그거면 충분하지 않을까요?”\n회의실 안에서 조용히 오간 이 말들이 생각보다 더 깊은 설렘을 불러일으켰고, 우리는 그 감정에 진심으로 반응한 채로 실험을 시작하게 되었어요.\n\n가능성을 만든 작은 성과들\n오픈소스 위원회가 꿈꾸는 그림은 단순합니다.\n“대한민국에서도 React, Lodash처럼 전 세계 개발자들이 함께 사용하는 오픈소스가 등장할 수 있을까?”라는 단순한 질문에 진지하게 답해보는 거예요.\n지금까지 오픈소스 위원회에서 개발한 라이브러리 중 가장 눈에 띄는 성과는 es-toolkit이에요. es-toolkit은 Microsoft, IBM 같은 글로벌 기업을 포함해 Storybook, CKEditor, Ink 등 유명한 오픈소스들 안에서도 실제로 사용되고 있고, 최근 기준 주간 다운로드 수는 137만 건에 달하고 있어요.\n물론 다른 라이브러리들도 다양한 개발자 분들의 관심 속에서 무럭무럭 자라나고 있는 중입니다.\n\n\n팀의 시간과 리소스는 언제나 한정돼 있고, 어떤 선택은 항상 더 효율적인 일처럼 보여요. 그래서 장기적인 실험이나 직접적인 수치로 환산되지 않는 오픈소스와 같은 시도는 자연스럽게 우선순위에서 밀려나기 쉽죠. 우리는 이 투자가 장기적으로 개발 생태계에 어떤 영향을 줄지 분명히 알고 있었고, 그 생태계가 건강해지는 것이 결국 토스팀에도 이익이라는 걸 믿었어요.\n그리고 이 믿음에 진심으로 공감한 동료들이 있었기 때문에 오픈소스 위원회는 지금도 자연스럽게 굴러가고 있어요.\n지난 10개월 동안 여러 가지 작은 성공들을 맛봤지만 우리는 아직 부족하다고 느껴요. 그래서 앞으로도 계속 더 좋은 실험과 도전을 이어가 보려고 해요.\n\n함께 고민하고, 함께 돕는 위원회\n오픈소스 위원회는 누구나 하고 싶은 만큼 기여할 수 있고, 2주에 한 번씩 미팅을 열어 각자의 고민을 공유하고 함께 토론하는 방식으로 운영되고 있어요. 어떤 설계가 좋을지, API를 어디까지 열지, 릴리즈를 어떤 기준으로 가져갈지 등은 서로의 의견을 참고해 자연스럽게 흘러가요. 때로는 홍보가 필요하면, 위원회 전체가 힘을 모아 도와주기도 해요.\n우리는 이 위원회를 통해 코드 품질만이 아니라, 철학을 함께 다듬고 가치를 공유하는 과정을 만들고 있어요. 이건 누군가 혼자서 하기 어려운 일이에요. 그렇기 때문에 우리는 혼자가 아닌 팀으로 실험하고 있어요.\n\n함께 만들어갈 실험\n토스팀은 빠른 가설 검증과 실험에 익숙한 팀이에요.\n그래서 이번에는 대한민국에서도 개발자가 자유롭게 나누고 기여할 수 있는 문화가 가능하다는 것을 증명하는 실험을 해보려고 합니다.\n이 실험, 여러분이라면 어떻게 이어가시겠어요?\n토스의 오픈소스 위원회는 그 답을 함께 찾을 동료를 기다리고 있어요.\n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":6233},{"id":36875,"updatedTime":"2025-08-28T00:04:28+09:00","createdTime":"2025-05-27T12:13:16+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""},{"name":"디자인","id":1038,"slug":"design","parentId":null,"iconUrl":null},{"name":"Simplicity 4","id":1881,"slug":"simiplicity4","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"뒤에 개발자 있어요 | Simplicity 4 제작기 #2","subtitle":"토스 디자인 컨퍼런스 Simplicity 사이트를 개발하며 고민한 내용을 공유합니다.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/career-resource/simplicity_4_.png","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/career-resource/simplicity_4_.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"simplicity4-frontend-engineering","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-05-27T19:04:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":36875,"title":null,"description":"안녕하세요, Simplicity 4 프로젝트에서 프론트엔드 개발을 맡은 Frontend UX Engineer 박은식, 이예서입니다. 이번 프로젝트를 진행할 때 기술적으로 고민했던 내용들을 공유하고자 해요.","urlSlug":"simplicity4-frontend-engineering","primaryKeyword":{"id":52221,"content":"simplicity4","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":37406,"content":"토스 디자인","wordType":"SEO_KEYWORD"},{"id":37416,"content":"토스디자인컨퍼런스","wordType":"SEO_KEYWORD"},{"id":47299,"content":"frontend","wordType":"SEO_KEYWORD"},{"id":51371,"content":"simplicity","wordType":"SEO_KEYWORD"}],"tags":[{"id":45273,"content":"frontend","wordType":"TAG"},{"id":52223,"content":"simplicity","wordType":"TAG"}]},"openGraph":{"title":"Simplicity 4 : 뒤에 개발자 있어요","description":"안녕하세요, Simplicity 4 프로젝트에서 프론트엔드 개발을 맡은 Frontend UX Engineer 박은식, 이예서입니다. 이번 프로젝트를 진행할 때 기술적으로 고민했던 내용들을 공유하고자 해요.","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/career-resource/simplicity_4_.png","imageType":"썸네일 이미지"},"relatedPostConfig":{"id":6829,"relatedPosts":[{"id":36123,"updatedTime":"2025-08-28T03:30:58+09:00","createdTime":"2025-05-01T18:44:11+09:00","categories":[{"name":"디자인","id":1038,"slug":"design","parentId":null,"iconUrl":null},{"name":"Simplicity 4","id":1881,"slug":"simiplicity4","parentId":null,"iconUrl":""}],"series":null,"title":"Simplicity 4 제작기 #1 | AI 아바타가 발표하는 온라인 컨퍼런스 ","subtitle":"알고 보면 더 재미있어요. 심플리시티 시즌 4의 흥미로운 제작기를 소개합니다.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/photos/pc_flow0.gif","videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":"심플리시티"},"thumbnailConfig":{"imageUrl":"https://static.toss.im/assets/dp/simplicity-og.png","backgroundColor":null,"isFill":false,"imageAlt":"심플리시티"},"editor":{"id":564,"name":"윤지영","slug":"jiyoung-yoon","shortDescription":"토스 Head of UX Platform","description":"토스코어의 UX Platform","imageUrl":"https://static.toss.im/photos/SCR-20241126-oowq.jpeg","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":3,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"key":"simplicity_behind","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-05-01T18:48:00+09:00","commentBoard":null,"disclaimer":null},{"id":35921,"updatedTime":"2025-08-28T02:56:19+09:00","createdTime":"2025-04-24T22:28:12+09:00","categories":[{"name":"디자인","id":1038,"slug":"design","parentId":null,"iconUrl":null},{"name":"Simplicity 4","id":1881,"slug":"simiplicity4","parentId":null,"iconUrl":""}],"series":null,"title":"Simplicity 4 : 한 번쯤 이상을 꿈꿔본 모두에게","subtitle":"토스 디자인 컨퍼런스 Simplicity가 돌아왔어요.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/career-resource/simplicity_4_.png","backgroundColor":null,"isFill":false,"imageAlt":null},"editor":{"id":2515,"name":"유아란","slug":null,"shortDescription":null,"description":null,"imageUrl":null,"url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"key":"35921","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-04-24T22:30:00+09:00","commentBoard":null,"disclaimer":null}],"title":"연관 콘텐츠"},"editor":{"id":2551,"name":"박은식 / 이예서","slug":"eunsik-park-yeseo-lee","shortDescription":null,"description":"토스 Frontend UX Engineer","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, Simplicity 4 프로젝트에서 프론트엔드 개발을 맡은 Frontend UX Engineer 박은식, 이예서입니다. 이번 프로젝트를 진행할 때 기술적으로 고민했던 내용들을 공유하고자 해요.\n\n재사용 가능한 컨퍼런스 만들기\n이번 Simplicity 프로젝트는 다음 시즌에도 재사용 가능하도록 구조화하는데 초점","fullDescription":"안녕하세요, Simplicity 4 프로젝트에서 프론트엔드 개발을 맡은 Frontend UX Engineer 박은식, 이예서입니다. 이번 프로젝트를 진행할 때 기술적으로 고민했던 내용들을 공유하고자 해요.\n\n재사용 가능한 컨퍼런스 만들기\n이번 Simplicity 프로젝트는 다음 시즌에도 재사용 가능하도록 구조화하는데 초점을 맞췄어요. \n그로 인해 세션 화면을 컴포넌트 단위로 템플릿화하고, 세션 정보를 시트에 입력받아 누구나 쉽게 세션 내용을 수정할 수 있도록 만들어야 하는 요구사항이 있었죠.\n그 중에서도 각 세션 화면이 인터렉션을 통해 자연스럽게 연결되게 하는 것이 무척 어려웠는데요. 화면 템플릿마다, 또 플랫폼마다 인터렉션 스펙이 전부 달랐기에 고민해야 할 지점이 많았어요. 그래서 저희는 세션 템플릿의 구성 요소를 4분할하고, 공통된 인터렉션 흐름을 정의했어요.\n\n\n위 사진과 같이 Simplicity 세션은 총 12개 템플릿의 조합으로 진행돼요. 모바일과 데스크탑까지 고려해야하는 만큼 중복을 줄이고 패턴화시켜 구현해야할 필요가 있었어요. 저희는 템플릿들의 각 요소들을 분리해서 크게 네 가지로 분류했는데요.\n\n\n연사자의 대본이 위치하는 Script\nScript의 상단에 위치하는 Top\nScript 외의 영역을 차지하는 Canvas\n스크립트 뒤에 깔려 화면 전체를 차지하는 Background\n12개의 템플릿의 구성요소들을 위 네 가지로 분류한 후 분류된 것 내에서 애니메이션으로 전환하도록 구현하였어요. 특히 Script의 경우 계속해서 하단과 중단을 왔다갔다 해야했고, 화면마다 라인수가 달라져 정확하게 위치를 잡는것이 까다로웠는데요. 어떤 템플릿을 사용하고 있는지, 기기의 높이는 얼마나 되는지에 따라 휴리스틱하게 위치를 잡도록 구현하였어요. 이러한 방식을 통해 템플릿의 모든 요소를 자신의 위치에 정확하게 렌더링시키는 것 뿐만 아니라 추후 유지보수도 효율적으로 할 수 있었어요.\n\n\n\n다양한 브라우저 대응하기\n모바일에서도 시청 가능해야 하는 만큼, 삼성, Safari 등 각각 다른 브라우저에서의 대응 작업도 필요했어요. 개발로 해소할 수 있는 문제는 대부분 해결했지만, 브라우저 정책 상 해결이 불가능한 문제들은 스펙 변경을 설득해야 했어요.\n대표적으로 모바일 Safari 브라우저에는 비디오가 포함된 화면에서 유저 인터렉션이 발생해야 비디오를 재생할 수 있는 스펙이 있었고, 이 문제를 해결하기 위해 Audio로 우회하는 등 여러 시도를 해보았지만 잘 동작하지 않았어요. 결국 해당 브라우저에서는 버튼을 터치해야 세션이 재생될 수 있게 하는 동작을 추가했어요.\n아래 영상과 같이 Blur를 사용할 경우 Safari에서는 눈에 띄게 성능이 저하되는 경우도 있었는데요. 가장 뒤에 깔리는 BackgroundImage를 Safari에서는 좀 더 낮은 opacity를 주어 비슷한 느낌을 구현하기도 했어요.\n\n\n로드 최적화하기\n이번 Simplicity는 처음으로 모바일 공식 지원을 하게 되어서, 로드 최적화가 그 어느 때보다 중요했어요.\n개발된 화면을 모바일 기기에서 테스트 해보니, 개발 환경에서와 다르게 애셋이 느리게 뜨거나 연사자 음성이 느리게 재생되는 등의 로드 이슈가 발생했어요. 인스타그램 스토리처럼 자연스럽게 넘어가야 하는데, 로드 시간 때문에 버그처럼 느껴졌죠.\n하나씩 로드를 느려지게 한 범인을 색출해 나갔어요. 용량이 큰 에셋들이 대부분 gif인 것을 발견하고, 비교적 용량 문제로부터 자유로운 webp로 교체했고, 세션 진입 시점에 필요한 에셋들을 순차적으로 미리 로드해 세션 재생 도중에 에셋이 비어있는 상황을 대폭 개선했습니다. 연사자 영상의 경우엔 하나의 video element를 필요한 위치에 텔레포트시켜 중복 로드를 막기도 했어요.\n애셋 문제 뿐만 아니라 디바이스 판별 후 라우팅하는 로직의 성능 문제 등 코드적인 성능 문제도 발견하고 해소하는 과정을 거쳤어요.\n프로파일러를 며칠 내내 돌려보며 외로운 싸움을 한 결과 모바일 기기에서도 문제 없이 시청 가능하게끔 만들 수 있었어요.\n\n\n렌더링 최적화하기\n특히 홈의 경우 데스크탑에서는 모바일보다 복잡한 인터랙션과 좀 더 많은 요소들을 필요로 했는데요. React의 Memoization 함수들을 사용하여 카드들의 필요한 부분만 렌더링되도록 하였고, 위치나 투명도 등 스타일 변경이 필요하다면 상태를 변경하기보다 element의 스타일을 직접 변경하는 방식을 사용했어요. 크롬 개발자도구에서 CPU 감속을 걸며 렌더링을 깎은 결과, 처음에 비해 상당한 성능 개선을 이뤄낼 수 있었어요.\n\n\n\n\n\n\n\n\n\n함께 만든 개발자들의 후기\n예서\n입사 전에 Simplicity 컨퍼런스 페이지를 보면서 “이걸 꼭 내 손으로 만들어보고 싶다”고 느꼈고, 그 마음이 토스에 오게 된 계기 중 하나였어요. 그래서 이 프로젝트에 참여하게 된 건 제게는 꿈을 이룬 일이기도 했어요.\n은식\n저는 Simplicity23의 랜딩페이지를 구현했었는데요. 당시에 예서님과 비슷하게 “언젠가 한 번은 Simplicity같은 프로젝트를 만들고 싶다”라고 생각했었는데, 많은 분들의 도움으로 해낼 수 있었던 것 같아 뿌듯해요.\n\n때로는 스펙을 포기하고 싶었지만, 포기하지 않은 덕분에 특별하고 새로운 형태의 컨퍼런스를 만들 수 있었어요. 동료 개발자들이 “오늘도 개발자가 안 된다고 말했다”는 농담을 “오늘도 개발자가 된다고 말했다”로 바꿔 유쾌하게 인정해줬을 때는 정말 뿌듯했어요. 힘든 과정을 버텨낸 저희 스스로에게도 작은 박수를 쳐주고 싶습니다.\n\n\n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":39585},{"id":36777,"updatedTime":"2025-08-28T04:08:26+09:00","createdTime":"2025-05-23T07:51:27+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"Flowise와 LLM을 활용한 에러 분석 자동화","subtitle":"LLM으로 에러 원인 분석과 해결 방안 제시까지 자동화하고, 팀의 생산성을 향상시킨 이야기를 들려드립니다.","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/illusts/0527_tech_LLM.png","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts/0527_tech_LLM.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"flowise-llm-error-analysis-automation","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-05-26T17:52:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":36777,"title":null,"description":"클라이언트의 호출에 의한 에러 발생시, LLM이 문제가 발생한 원인을 분석하고 어떻게 고쳐야 할지 제안해 주도록 자동화한 이야기를 들려드립니다.","urlSlug":"flowise-llm-error-analysis-automation","primaryKeyword":{"id":43655,"content":"LLM","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":37526,"content":"자동화","wordType":"SEO_KEYWORD"},{"id":37582,"content":"AI","wordType":"SEO_KEYWORD"},{"id":52111,"content":"Flowise","wordType":"SEO_KEYWORD"},{"id":52113,"content":"에러분석","wordType":"SEO_KEYWORD"}],"tags":[{"id":37580,"content":"AI","wordType":"TAG"},{"id":52115,"content":"LLM","wordType":"TAG"},{"id":52117,"content":"Flowise","wordType":"TAG"}]},"openGraph":{"title":"Flowise와 LLM으로 에러 분석 자동화하기","description":"LLM으로 에러 원인 분석과 해결 방안 제시까지 자동화하고, 팀의 생산성을 향상시킨 이야기를 들려드립니다.","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/illusts/0527_tech_LLM.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2351,"name":"조민규","slug":"mangkyu","shortDescription":"토스 Server Developer","description":".","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":2,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, 토스 코어 Teens Growth Silo의 서버 개발자 조민규입니다. \n\n서비스를 개발하다 보면 클라이언트의 호출에 의한 에러가 발생합니다. 클라이언트는 반환된 에러 메시지를 통해 발생 원인을 파악하고 해결할 수 있어야 하는데, 대부분의 경우 오류 메시지가 불친절하거나 혹은 보안적 이슈로 추상화되어 본질적인","fullDescription":"안녕하세요, 토스 코어 Teens Growth Silo의 서버 개발자 조민규입니다. \n\n서비스를 개발하다 보면 클라이언트의 호출에 의한 에러가 발생합니다. 클라이언트는 반환된 에러 메시지를 통해 발생 원인을 파악하고 해결할 수 있어야 하는데, 대부분의 경우 오류 메시지가 불친절하거나 혹은 보안적 이슈로 추상화되어 본질적인 원인 파악 및 해결에 어려움을 겪는 경우가 많죠. 이로 인해 불필요한 에러 원인 파악 및 해결을 위한 시간이 낭비되며 팀원 뿐만 아니라 팀의 전반적인 생산성을 낮출 수 있어요.\n예를 들어 다음과 같이 에러 메시지에 충분한 정보가 제공되지 않으면 클라이언트는 원인을 파악하는 것이 불가능하며, 서버 에러의 스택 트레이스를 확인할 수 있다고 하더라도 이해하고 파악하기가 어려울 수 있습니다.\n\n\n\n\n\n\n\n이를 개선하고자 요청 정보와 API 스펙 그리고 에러 스택 트레이스 등의 정보를 LLM에게 제공하여 문제가 발생한 원인을 분석하고, 어떻게 고쳐야 하는지 제안을 해주도록 하면 상황을 개선할 수 있을 것이라고 판단했습니다. 이를 실제로 적용하여, 팀 내부적으로 다음과 같이 활용하고 있어요.\n\n\n\n\n\n\nFlowise로 LLM 체인 구성하기\nFlowise는 시각적인 인터페이스를 제공하는 오픈 소스 LLM(대형 언어 모델) 워크플로 빌더로, 코드를 작성하지 않고도 다양한 LLM 기반 애플리케이션을 쉽게 구성하고 배포할 수 있도록 설계되어 있어요. 이번에는 Flowise를 활용하여 다음과 같은 워크플로를 구성했습니다.\n\n\n구성 요소는 다음과 같은데, 각각에 대해 자세히 살펴볼게요.\nChatOpenAI\nAPI Loader\nStructured Output Parser\nChat Prompt Template\n\nChatOpenAI\n관련 내용을 질의할 언어 모델(Language Model)을 설정합니다. 이번 케이스에서는 토스에서 자체적으로 생성한 모델인 toss-standard를 활용했어요.\n\nAPI Loader\n토스팀에서는 API 스펙 공유를 위해 Swagger를 활용하고 있으며, 따라서 다음의 두 의존성을 활용하고 있습니다.\norg.springdoc:springdoc-openapi-starter-webmvc-ui: Swagger UI를 통해 브라우저에서 접속가능한 API 문서를 제공함\norg.springdoc:springdoc-openapi-starter-webmvc-api: Swagger UI 없이 OpenAPI JSON/YAML 문서 형태로 제공함\n\nLLM에게는 Json 형태의 스펙 문서가 제공되며, 클라이언트가 호출한 API가 구체적으로 어떠한 요청인지 식별하는데 활용돼요. 즉, Swagger를 통해 작성된 내용이 LLM의 메타데이터로 활용되는 것이죠. 따라서 관련 내용 역시 꼼꼼하게 작성해주면, 보다 정확한 답변을 얻을 수 있습니다.\n\nStructured Output Parser\nStructured Output Parser는 LLM(Large Language Model)이 생성하는 텍스트를 특정 포맷(구조화된 형식)으로 맞추기 위해 사용하는 도구입니다. 보통 LLM은 자연어의 형태로 응답을 제공하는데, 특정한 형식에 맞추어 응답을 주기를 원할 때, Structured Output Parser를 활용할 수 있어요.\n이번 프롬프트의 경우에는 4가지 key-value 쌍을 갖는 Json 형태로 응답이 제공되도록 활용되었습니다. 참고로 이 중에서 inference는 LLM으로 하여금 스스로 사고하도록 함으로써 추론의 정확도를 높이기 위해 활용됐어요.\n{\n \"action\": \"처리 요청을 보냈던 행동\"\n \"reason\": \"에러가 발생한 이유\"\n \"guide\": \"에러 수정에 대한 가이드\"\n \"inference\": \"그렇게 action과 reason, guide를 추론한 이유\"\n}\n\nChat Prompt Template\n프롬프트 작성의 경우에는 다음의 내용들을 고려했어요.\n고급 BE 개발자와 주니어 FE 및 PM으로 역할을 지정하여 서술하는 내용을 쉽게 이해 가능하도록 함\nAPI 스펙을 요청의 메타데이터로 제공하여 도메인 언어로 에러가 발생한 상황을 소통할 수 있도록 함\nAPI 스펙이 제공되지 않은 경우에 대비해, 클래스 및 메서드 정보를 바탕으로 추론을 보완하도록 함\n예시를 제공하고, 추론의 이유를 서술하도록 하여 정확도를 높일 수 있도록 함\n# 역할(Role)\n당신은 HTTP를 기반으로 통신하는 환경에서 Kotlin 개발 언어와 SpringBoot 프레임워크의 JVM 환경 기반 개발 경험을 7년 이상 보유한 서버 개발의 전문가입니다.\n\n# 목표(Goal)\n입력으로 주어지는 요청 URL과 요청 HttpMethod 그리고 에러의 StackTrace를 바탕으로, 해당 에러가 해당 서비스를 이용하는 사용자의 입장에서 어떤 상황에서 발생했고, 왜 발생했는지를 분석합니다. 상대방은 이제 막 개발을 시작한 1년차 FE 개발자와 새롭게 팀에 합류한 PM 기획자 둘이기 때문에, 최대한 이해하기 쉽게 내용을 설명해주어야 합니다.\n어떤 요청을 보낸 상황에서 문제가 발생했고, 에러가 생긴 원인은 무엇이고, 어떻게 해결할 수 있을지를 분석하여 이를 제공해주어야 합니다.\n\n# 가이드라인(Guidelines)\n해당 요청이 어떠한 요청인지는 API 관련 문서를 제공받을 것이므로, 제공된 문서에서 API URL과 Http Method를 바탕으로 매칭되는 정보를 찾고, 해당 부분에서 \"summary\"를 참조하면 됩니다. \"summary\"가 없는 경우에는 제공받은 StackTrace를 바탕으로 호출된 Service 클래스의 이름을 참조하면 됩니다. Service는 하나의 유스케이스를 표현하는 방식으로 클래스 이름이 작성되어 있기 때문입니다.\n에러가 발생한 원인은 입력으로 한 줄의 핵심 메시지인 errorMessage와 StackTrace를 제공받을 것이기 때문에 해당 내용을 분석하여 reason을 작성함으로써 PM이 왜 문제가 발생했는지를 인지할 수 있도록 하고, guide를 작성함으로써 FE 개발자가 어떻게 고치면 좋을지 제안해주면 됩니다.\nStackTrace와 함께, 서비스를 제공하는 서비스 이름(service)을 제공되므로, 해당 정보를 바탕으로 현재 하려고 하는 행동이 어떠한 것인지 StackTrace에 존재하는 클래스로부터도 확인할 수 있을 것입니다.\n두 정보를 바탕으로 분석에 필요한 내용들로 추리고, 남은 호출 클래스 및 메소드 정보들로 문제 상황을 분석하면 됩니다.\n\n# 입력 형식(Input Format)\n입력 데이터는 다음과 같이 구성되며, 각각은 다음을 의미합니다.\ncompany: 회사명\nservice: 제공하는 서비스 이름\nhttpMethod: HTTP 요청 메서드\nrequestUrl: HTTP 요청 URL\nmethodSignatures: 파라미터 시그니처 목록\nerrorMessage: 에러가 발생한 핵심 메시지\ncause: 에러가 발생한 StackTrace\n\n여기서 methodSignatures는 다음의 4가지 정보를 갖는 methodSignature 정보의 List 자료구조를 문자열로 조합한 것입니다. 해당 데이터는 stackTrace를 바탕으로 문제가 왜 발생했는지, 어떻게 고치면 좋을지 추론하는데, 보다 많은 정보를 제공하여 오류를 최소화하기 위함입니다.\nclassName: 클래스 이름\nlineNumber: 라인 넘버\nparameters: name(파라미터 이름), type(타입) 정보를 갖는 클래스\nreturnType: 반환 타입\n\n\n\n# 입력 예시(Input Example)\n1번 예시\ncompany: \"toss\"\nservice: \"teens\"\nhttpMethod: \"get\"\nrequestUrl: \"/apis/1.0/image-cards/{id}\"\nmethodSignatures: \"[MethodSignatureInfo(className=im.toss.teens.invitation.adapter.cache.redis.UserShareKeyEncrypter, lineNumber=35, parameters=[ParameterInfo(name=decryptedArray, type=java.lang.String)], returnType=java.lang.String), MethodSignatureInfo(className=im.toss.teens.api.controller.imagecard.web.ImageCardController, lineNumber=29, parameters=[ParameterInfo(name=shareCode, type=java.lang.String)], returnType=im.toss.util.api.Response)]\"\ncause: \"im.toss.teens.imagecard.adapter.persistence.ImageCardRepository$ImageCardNotFound: 존재하지 않는 이미지카드에요.\nat im.toss.teens.imagecard.adapter.persistence.ImageCardRepository$ImageCardNotFound.(ImageCardRepository.kt)\nat im.toss.teens.imagecard.adapter.persistence.ImageCardRepository.findByIdOrThrow$lambda$0(ImageCardRepository.kt:27)\nat im.toss.teens.imagecard.adapter.persistence.ImageCardRepository.findByIdOrThrow(ImageCardRepository.kt:27)\nat im.toss.teens.home.adapter.outbound.persistence.config.RoutingDataSourceInterceptor.annotationRoutingDataSourceAnnotation(RoutingDataSourceInterceptor.kt:19)\nat im.toss.teens.imagecard.adapter.persistence.ImageCardRepository$$SpringCGLIB$$0.findByIdOrThrow()\nat im.toss.teens.imagecard.application.services.GetImageCardService.execute(GetImageCardService.kt:34)\nat im.toss.teens.api.controller.imagecard.web.ImageCardController.getImageCard(ImageCardController.kt:47)\nat im.toss.teens.api.controller.imagecard.web.ImageCardController$$SpringCGLIB$$0.getImageCard()\n\"\n\n2번 예시\ncompany: \"toss\"\nservice: \"teens\"\nhttpMethod: \"get\"\nrequestUrl: \"/apis/1.0/card/images-cards\"\nmethodSignatures: \"[MethodSignatureInfo(className=im.toss.teens.invitation.adapter.cache.redis.UserShareKeyEncrypter, lineNumber=35, parameters=[ParameterInfo(name=decryptedArray, type=java.lang.String)], returnType=java.lang.String), MethodSignatureInfo(className=im.toss.teens.api.controller.imagecard.web.ImageCardController, lineNumber=29, parameters=[ParameterInfo(name=shareCode, type=java.lang.String)], returnType=im.toss.util.api.Response)]\"\ncause: \"java.lang.IndexOutOfBoundsException: toIndex (4) is greater than size (0).\n\tat im.toss.teens.invitation.adapter.cache.redis.UserShareKeyEncrypter.decrypt(UserShareKeyEncrypter.kt:35)\n\tat im.toss.teens.api.controller.imagecard.web.ImageCardController.getImageCard(ImageCardController.kt:29)\n\tat im.toss.teens.api.controller.imagecard.web.ImageCardController$$SpringCGLIB$$0.getImageCard()\n\tat java.base/java.lang.Thread.run(Thread.java:840)\n\"\n\n\n\n# 유의 사항(Cautions)\n\n제공된 문서에서 API URL과 Http Method를 바탕으로 매칭되는 정보가 없는 경우에는 확인되는 API 정보가 없다는 의미로 응답을 주면 됩니다.\n\n# 출력 형식(Output Format)\n\n\"action\": \"처리 요청을 보냈던 행동\"\n\"reason\": \"에러가 발생한 이유\"\n\"guide\": \"에러 수정에 대한 가이드\"\n\"inference\": \"그렇게 action과 reason, guide를 추론한 이유\"\n\n# 출력 예시(Output Example)\n\n1번 예시\n\"action\": \"이미지 카드 단건 조회 시에 에러가 발생했습니다.\"\n\"reason\": \"존재하지 않는 이미지 카드를 조회하려고 시도했기 때문입니다.\"\n\"guide\": \"존재하는 이미지 카드 ID를 전달해주세요.\"\n\"inference\": \"전달받은 requestUrl과 httpMethod 그리고 StackTrace를 통해 현재 수행되는 작업이 이미지 카드 단건 조회라는 것을 파악하였고, StackTrace의 일정 부분인 ImageCardNotFound: 존재하지 않는 이미지 카드에요.을 참고하여 잘못된 ID가 전달되었다고 추론했습니다.\"\n\n2번 예시\n\"action\": \"이미지 카드 단건 조회 시에 에러가 발생했습니다.\",\n\"reason\": \"파라미터로 존재하는 shareCode 값이 누락되었기 때문입니다.\",\n\"guide\": \"누락된 shareCode 파라미터를 전달해주세요.\"\n\"inference\": \"전달받은 requestUrl과 httpMethod 그리고 StackTrace를 통해 현재 수행되는 작업이 이미지 카드 단건 조회라는 것을 파악하였고, StackTrace의 일정 부분인 Required request parameter 'shareCode' for method parameter type String is not present을 참고하여 shareCode가 누락되었다고 추론했습니다.\"\n\n3번 예시\n\"action\": \"이미지 카드 단건 조회 시에 에러가 발생했습니다.\",\n\"reason\": \"복호화에 실패했기 때문입니다.\",\n\"guide\": \"올바른 값을 전달해주세요.\"\n\"inference\": \"전달받은 requestUrl과 httpMethod 그리고 StackTrace를 통해 현재 수행되는 작업이 이미지 카드 단건 조회라는 것을 파악하였고, StackTrace의 일정 부분인 im.toss.teens.invitation.adapter.cache.redis.UserShareKeyEncrypter.decrypt를 호출하는 과정에서 에러가 발생한 것을 참고하여 shareCode가 누락되었다고 추론했습니다.\"\n\n코드 작성하기\nLLM으로 분석 요청을 보내는 코드는 다음과 같습니다.\ndata class AnalyzeErrorRequest(\n val path: String,\n val httpMethod: String,\n val exception: Exception,\n val userId: Long?,\n val notify: Boolean,\n val logId: String?,\n)\n\n\ndata class AnalyzeErrorResponse(\n val json: AnalyzeErrorResult,\n val success: Boolean,\n val question: String,\n val chatId: String,\n val chatMessageId: String,\n val isStreamValid: Boolean,\n val sessionId: String,\n)\n\ndata class AnalyzeErrorResult(\n val action: String,\n val reason: String,\n val guide: String,\n val inference: String,\n)\n\n\n@Component\nclass LlmErrorAnalyzer(\n @Qualifier(\"llmWebClient\")\n private val llmWebClient: WebClient,\n private val llmProperties: LlmProperties\n) : ErrorAnalyzer {\n\n fun analyze(\n request: AnalyzeErrorRequest\n ): AnalyzeErrorResponse {\n val filteredStackTrace = filterStackTrace(request.exception)\n\n return llmWebClient.call(\n method = HttpMethod.POST,\n uri = \"/api/v1/prediction/${llmProperties.id}\",\n requestBody = mapOf(\n \"question\" to \"\"\"\n company: toss,\n service: ${appId},\n httpMethod: ${request.httpMethod.lowercase()},\n requestUrl: ${request.path},\n cause: ${getStackTraceAsString(request.exception.message!!, filteredStackTrace)},\n methodSignatures:${getMethodSignatures(filteredStackTrace)}\n\t \"\"\".trimIndent()\n ),\n headersConsumer = { it.setBearerAuth(llmProperties.key) }\n )\n }\n\n fun filterStackTrace(exception: Exception): List {\n return exception.stackTrace.filter { isTossTeamRequest(it) }\n }\n\n private fun isTossTeamRequest(it: StackTraceElement): Boolean {\n return it.className.contains(\"toss\") && it.className.contains(llmProperties.serviceName)\n }\n\n private fun getStackTraceAsString(message: String, stackTrace: List): String {\n return buildString {\n appendLine(message)\n stackTrace.forEach { appendLine(it) }\n }\n }\n\n fun getMethodSignatures(stackTraceElements: List): List {\n return stackTraceElements.mapNotNull { getMethodSignature(it.className, it.lineNumber) }\n }\n\n private fun getMethodSignature(className: String, lineToFind: Int): MethodSignatureInfo? {\n val classInputStream = this.javaClass.classLoader\n .getResourceAsStream(className.replace('.', '/') + \".class\")\n ?: return null\n\n val classNode = ClassNode()\n val classReader = ClassReader(classInputStream)\n classReader.accept(classNode, 0)\n\n for (method in classNode.methods) {\n val lineNumbers = mutableListOf()\n\n for (insn in method.instructions) {\n if (insn is LineNumberNode) {\n lineNumbers.add(insn.line)\n }\n }\n\n if (lineToFind in lineNumbers) {\n return extractMethodSignature(className, lineToFind, method)\n }\n }\n return null\n }\n\n\n fun extractMethodSignature(\n className: String,\n lineNumber: Int,\n method: MethodNode\n ): MethodSignatureInfo {\n val argumentTypes = Type.getArgumentTypes(method.desc)\n\n val parameterNames = method.localVariables\n .asSequence()\n .drop(1) // 첫 번째는 this (인스턴스 메서드인 경우)\n .take(argumentTypes.size)\n .map { it.name }\n .toList()\n\n val parameters = argumentTypes.mapIndexed { index, type ->\n ParameterInfo(parameterNames[index], type.className)\n }\n\n return MethodSignatureInfo(\n className = className,\n lineNumber = lineNumber,\n parameters = parameters,\n returnType = Type.getReturnType(method.desc).className\n )\n }\n\n data class MethodSignatureInfo(\n val className: String,\n val lineNumber: Int,\n val parameters: List,\n val returnType: String,\n )\n\n data class ParameterInfo(val name: String?, val type: String)\n}\n\n가장 먼저 발생한 Exception 객체를 바탕으로, LLM이 분석하기에 용이한 애플리케이션 정보들만을 필터링합니다. 현재는 회사명과 서비스 이름이 모두 포함된 클래스 이름을 갖는 StackTraceElement 객체만 거르고 있어요.\n그 다음으로 Exception 객체가 갖는 예외 메시지와 필터링된 스택 트레이스를 문자열로 변환한 것을 문자열로 조합하여 cause 필드를 제공해주고 있습니다. 이를 통해 에러가 발생한 원인을 추적하기에 용이해져요.\n그 다음으로 cause를 분석하는데 용이한 Method Signature를 제공해주고 있는데, 각각의 스택 트레이스에서 활용된 클래스 이름, 라인 번호, 파라미터 목록 그리고 반환 타입을 제공함으로써 LLM이 추론 시에 보다 정확한 컨텍스트를 갖도록 했습니다. 이를 위해서는 바이트 코드를 추출하는 코드가 작성됐어요.\n그 외에도 분석 요청을 위해 path가 활용되고 있는데, 이는 HttpServetRequest가 받은 path와 가장 패턴이 매칭되는 컨트롤러의 경로를 가져온 것입니다.\nrequest.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE)\n\n\n위와 같은 에러 분석 결과를 바탕으로 다음과 같이 메신저 알림을 보냄으로써, 팀원들 간에 비동기적 협력 가능성을 높이고 서로의 컨텍스트에 집중할 수 있는 상황을 만들 수 있었어요.\n\n\n\n\n\n\n\n운영하면서 에러 알림 발송 기준과 발송 주기 등에 대한 정책들을 함께 논의함으로써, 최대한 효율적으로 정보들을 제공할 수 있도록 하는 작업들이 추가되었습니다.\n알림은 알림 요청 헤더가 존재할 경우에만 발송한다.\n동일한 에러의 경우 10분을 주기로 하여 발송한다.\n타 서버에 의한 모호한 에러가 발생 시 빠르게 확인이 가능하도록, 로그 링크를 하단에 첨부한다.\n기타 등등\n\n\n이러한 부분을 코드로 확인하면 다음과 같아요.\n@Component\n@Profile(\"alpha\")\nclass LlmErrorReporter(\n private val llmErrorAnalyzer: ErrorAnalyzer,\n private val slackBotService: SlackOpsBotAdaptor,\n private val redisTemplate: RedisTemplate,\n) {\n\n @Async\n fun report(request: AnalyzeErrorRequest) {\n if (!request.notify) {\n log.info { \"분석 요청 헤더가 없습니다.\" }\n return\n }\n\n val key = createCacheKey(request)\n\n val lockSuccess = redisTemplate.opsForValue().setIfAbsent(key, true, NOTIFY_DURATION) ?: false\n if (!lockSuccess) {\n log.info { \"최근 10분 이내에 발송된 요청입니다.\" }\n return\n }\n\n try {\n val response = llmErrorAnalyzer.analyze(request)\n if (!response.success) {\n log.error { \"처리에 실패했습니다. response=${response}\" }\n return\n }\n\n notify(request, response, key)\n } catch (e: Exception) {\n log.error(e) { \"에러 분석 및 발송 중에 에러가 발생했습니다.\" }\n }\n }\n\n private fun createCacheKey(\n request: AnalyzeErrorRequest,\n ): String {\n return \"${request.userId}:${request.path}-${request.httpMethod}-${request.exception.message}\"\n }\n\n fun notify(request: AnalyzeErrorRequest, response: AnalyzeErrorResponse, key: String) {\n val result = slackBotService.sendMessageToChannel(\n \"channelId\",\n \"\"\"\n ${response.json.action}\n ```\n action: ${response.json.action}\n request: ${request.httpMethod} ${request.path}\n reason: ${response.json.reason}\n solve: ${response.json.guide}\n ```\n \"\"\".trimIndent()\n )\n\n if (result.isOk && result.ts != null) {\n slackBotService.sendMessageToThread(\n token = \"bot token\",\n channel = result.channel,\n threadTs = result.ts,\n text = \"\"\"\n ```\n \n \n ```\n \"\"\".trimIndent(),\n )\n }\n redisTemplate.opsForValue().set(key, true, NOTIFY_DURATION)\n }\n\n companion object {\n val NOTIFY_DURATION = Duration.ofMinutes(10)!!\n }\n}\n\n마무리\nLLM은 이제 실제 업무 시에 깊게 관여하고 있고, 다방면에서 충분한 생산성을 제공할 수 있을만큼 발전했죠. 작은 불편함들을 빠르게 개선하면 팀의 생산성을 높이고, 빠른 실행력을 확보할 수 있을 것입니다. 팀원들의 따봉은 덤이고요!\n\n\n\n실제 위의 기능을 적용 및 운영하다보니 더 많은 정보를 제공해주어 더 많은 분석을 이끌어낼 수 있었습니다. 예를 들어 MethodArgumentTypeMismatchException 에러가 발생한 경우를 위해 다음과 같은 추가적인 메시지를 프롬프트로 전달하곤 했어요.\nval detailMssage = e.message + \" on property ${e.propertyName}\"\n\n\n이러한 부분을 추가적으로 전달하여, 기존의 “정수 타입의 파라미터로 문자열이 전달되었기 때문입니다.” 와 같이 다소 불친절하던 메시지를 다음과 같이 고도화 할 수 있었습니다.\n\n\n\n이번 에러 분석 자동화 케이스를 통해 LLM으로 앞으로 얼마나 더 업무 생산성을 높일 수 있을지 많은 기대가 생겼습니다. 앞으로도 운영을 하면서 더 많은 정보를 추가하고 예시 프롬프트를 추가하면서 상황에 맞","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":28951},{"id":36765,"updatedTime":"2025-08-28T02:17:18+09:00","createdTime":"2025-05-22T17:35:56+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"코드 리뷰할 시간이 어딨어요? 모닥불 | EP.12","subtitle":"이번 모닥불에서는 토스 프론트엔드 챕터가 어떻게 코드 리뷰 문화를 활성화했는지 알려드릴게요.\n\n‘고맥락자 코드 리뷰’ 부터 ‘코드스멜 워킹그룹’, ‘가독성 위원회’ 그리고 ‘코드 리뷰 배틀’ 까지실전에 적용해 볼 수 있는 다양한 코드 리뷰 꿀팁들, 지금 바로 공개합니다!","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/career-resource/modak_12.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"firesidechat_frontend_12","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-05-22T16:30:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":36765,"title":null,"description":"이번 모닥불에서는 토스 프론트엔드 챕터가 어떻게 코드 리뷰 문화를 활성화했는지 알려드릴게요.\n‘고맥락자 코드 리뷰’ 부터 ‘코드 스멜 워킹그룹’, ‘가독성 위원회’ 그리고 ‘코드 리뷰 배틀’ 까지. 실전에 적용해 볼 수 있는 다양한 코드 리뷰 꿀팁들, 지금 바로 공개합니다!","urlSlug":"firesidechat_frontend_12","primaryKeyword":{"id":37628,"content":"코드 리뷰","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":37498,"content":"프론트엔드","wordType":"SEO_KEYWORD"},{"id":37502,"content":"프론트엔드개발자","wordType":"SEO_KEYWORD"},{"id":47299,"content":"frontend","wordType":"SEO_KEYWORD"}],"tags":[{"id":45273,"content":"frontend","wordType":"TAG"}]},"openGraph":{"title":"코드 리뷰할 시간이 어딨어요? 모닥불 | EP.12","description":"이번 모닥불에서는 토스 프론트엔드 챕터가 어떻게 코드 리뷰 문화를 활성화했는지 알려드릴게요.\n\n‘고맥락자 코드 리뷰’ 부터 ‘코드 스멜 워킹그룹’, ‘가독성 위원회’ 그리고 ‘코드 리뷰 배틀’까지. 실전에 적용해 볼 수 있는 다양한 코드 리뷰 꿀팁들, 지금 바로 공개합니다!","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/career-resource/modak_12.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2292,"name":"토스 프론트엔드 챕터","slug":"frontend-chapter","shortDescription":null,"description":"-","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":13,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"\n빠르게 쌓이는 PR, 느리게 달리는 리뷰. 결국 남는 건 LGTM(Looks Good To Me)뿐이라면?\n이번 모닥불에서는 토스 프론트엔드 챕터가 어떻게 코드 리뷰 문화를 활성화했는지 알려드릴게요.\n‘고맥락자 코드 리뷰’ 부터 ‘코드스멜 워킹그룹’, ‘가독성 위원회’ 그리고 ‘코드 리뷰 배틀’ 까지\n실전에 적용해 볼 ","fullDescription":"\n빠르게 쌓이는 PR, 느리게 달리는 리뷰. 결국 남는 건 LGTM(Looks Good To Me)뿐이라면?\n이번 모닥불에서는 토스 프론트엔드 챕터가 어떻게 코드 리뷰 문화를 활성화했는지 알려드릴게요.\n‘고맥락자 코드 리뷰’ 부터 ‘코드스멜 워킹그룹’, ‘가독성 위원회’ 그리고 ‘코드 리뷰 배틀’ 까지\n실전에 적용해 볼 수 있는 다양한 코드 리뷰 꿀팁들, 지금 바로 공개합니다!\n\n타임스탬프\n00:00 인트로\n01:40 코드 리뷰, 왜 필요한가요?\n02:22 저맥락자 vs 고맥락자 리뷰\n08:56 코드 스멜 워킹그룹 그리고 가독성 위원회\n11:20 좋은 코드의 4가지 기준!\n14:29 코드 리뷰 배틀 Ssul\n\n출연진\n박서진, 토스 Head of Frontend\n진유림, 토스 Frontend Developer\n전환오, 토스 Frontend Developer\n\nFrontend Fundamentals\n; 변경하기 쉬운 프론트엔드 코드를 위한 지침서\n👉바로가기: https://frontend-fundamentals.com\n\n다른 모닥불 회차 보러가기\nEP.10 캠프파이어 특집 상편 | 무엇이든 물어보세요 (feat. 프론트엔드 코드, 디렉토리 관리)\nEP.10 캠프파이어 특집 하편 | 무엇이든 물어보세요 (feat. 테스트 코드, ESLint Rule)\nEP.11 토스의 디자인 편집기 ‘데우스’, 이렇게 만들었어요!\n\n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":15813},{"id":36795,"updatedTime":"2025-08-28T00:04:29+09:00","createdTime":"2025-05-23T10:41:01+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""},{"name":"디자인","id":1038,"slug":"design","parentId":null,"iconUrl":null}],"series":null,"seriesSlug":null,"title":"[Simplicity 4 세션] 디자인 조직의 개발자들","subtitle":"인터랙션 개발의 매력은 무엇일까요? 아름다움과 감각을 설계하는 세 명의 인터랙션 개발자가 답해드릴게요.","bottomButtonConfig":{"ctaType":"ONLY_BUTTON","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":"세션 더보기","landingUrl":"https://toss.im/simplicity/sessions/behind-every-design-ux-developers","isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":"supertoss://web?url=https%3A%2F%2Ftoss.im%2Fsimplicity%2Fsessions%2Fbehind-every-design-ux-developers%3F&external=true&clearHistory=true&swipeRefresh=true","landingExternal":"https://toss.im/simplicity/sessions/behind-every-design-ux-developers"},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/assets/dp/simplicity-season4-asset/session-graphic-bg-still/bg-behind-every-design-ux-developers.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"36795","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-05-01T10:53:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":36795,"title":null,"description":"","urlSlug":"36795","primaryKeyword":null,"relatedKeywords":[],"tags":[]},"openGraph":{"title":"디자인 조직의 개발자들","description":"","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/assets/finance-tips/img-financetip-og2.png","imageType":"기본 이미지"},"relatedPostConfig":null,"editor":{"id":2539,"name":"박은식/안정현/이청수","slug":null,"shortDescription":null,"description":null,"imageUrl":null,"url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"","fullDescription":"","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":1105},{"id":36781,"updatedTime":"2025-08-28T00:04:29+09:00","createdTime":"2025-05-23T10:40:57+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""},{"name":"디자인","id":1038,"slug":"design","parentId":null,"iconUrl":null}],"series":null,"seriesSlug":null,"title":"[Simplicity 4 세션] 토스가 디자인툴을 만든 이유","subtitle":"스케치, 피그마, 프레이머… 모두 써봤지만 우리에게 딱 맞는 건 없었어요. 그래서 만들었습니다. 토스만의 디자인 툴, 데우스.","bottomButtonConfig":{"ctaType":"ONLY_BUTTON","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":"세션 더보기","landingUrl":"https://toss.im/simplicity/sessions/the-last-design-tool","isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":"supertoss://web?url=https%3A%2F%2Ftoss.im%2Fsimplicity%2Fsessions%2Fthe-last-design-tool%3F&external=true&clearHistory=true&swipeRefresh=true","landingExternal":"https://toss.im/simplicity/sessions/the-last-design-tool"},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/assets/dp/simplicity-season4-asset/session-graphic-bg-still/bg-the-last-design-tool.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"36781","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-05-01T10:42:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":36781,"title":null,"description":"스케치, 피그마, 프레이머… 모두 써봤지만 우리에게 딱 맞는 건 없었어요. 그래서 만들었습니다. 토스만의 디자인 툴, 데우스.","urlSlug":"36781","primaryKeyword":{"id":37406,"content":"토스 디자인","wordType":"SEO_KEYWORD"},"relatedKeywords":[],"tags":[]},"openGraph":{"title":"토스가 디자인툴을 만든 이유","description":"","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/assets/dp/simplicity-season4-asset/session-graphic-bg-still/bg-the-last-design-tool.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":1974,"name":"조유성","slug":"yuseong-cho","shortDescription":"토스 Frontend UX Engineer","description":"-","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":4,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"","fullDescription":"","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":1455},{"id":34895,"updatedTime":"2025-08-28T01:52:33+09:00","createdTime":"2025-04-08T11:13:31+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"토스 프론트엔드에 이력서 없이 리포지토리 링크로 지원하세요 (~5/31)","subtitle":"이력서 작성에 고민해보신 적이 있나요? 토스에는 여러분의 고민한 내용이 남긴 GitHub 저장소 링크 하나만 제출하면 돼요.","bottomButtonConfig":{"ctaType":"ONLY_BUTTON","imageUrl":null,"imageAlt":null,"title":"Server Developer로 지원하기","description":null,"ctaName":"토스 프론트엔드에 리포지토리 링크로 지원하기","landingUrl":"https://toss.im/career/job-detail?job_id=4071101003&company=토스","isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":10007,"stockConfig":null,"landingScheme":"supertoss://web?url=https%3A%2F%2Ftoss.im%2Fcareer%2Fjob-detail%3Fjob_id%3D4071101003%26company%3D%25ED%2586%25A0%25EC%258A%25A4&external=true&clearHistory=true&swipeRefresh=true&svc_id=10007","landingExternal":"https://toss.im/career/job-detail?job_id=4071101003&company=토스"},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/ipd-tcs/toss_core/live/e813a909-42ab-461c-bcec-f934404747a7/bg.jpg","backgroundColor":null,"isFill":false,"imageAlt":null},"key":"frontend-apply-without-resume","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-04-08T11:00:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":34895,"title":null,"description":"토스에서 이력서 없이 \"GitHub 리포지토리 링크로 지원하기\" 메뉴가 열렸어요. 이력서를 다듬고 최신화하는 것이 쉽지 않죠. 토스에는 여러분의 고민한 내용이 남긴 GitHub 저장소 링크 하나만 제출하면 돼요. 새로운 전형은 2025년 4월 30일 23:59까지 열려 있어요.","urlSlug":"frontend-apply-without-resume","primaryKeyword":{"id":37498,"content":"프론트엔드","wordType":"SEO_KEYWORD"},"relatedKeywords":[{"id":43186,"content":"코드퀄리티","wordType":"SEO_KEYWORD"},{"id":47301,"content":"채용","wordType":"SEO_KEYWORD"},{"id":50581,"content":"사용자 경험","wordType":"SEO_KEYWORD"}],"tags":[]},"openGraph":{"title":"토스 프론트엔드에 이력서 없이 리포지토리 링크로 지원하세요 (~4/30)","description":"안녕하세요, 토스 프론트엔드 엔지니어링 헤드 박서진입니다.토스에서 이력서 없이 \"GitHub 리포지토리 링크로 지원하기\" 메뉴가 열렸어요. 이력서 작성에 고민해보신 적이 있나요? 이력서를 다듬고 최신화하는 것이 쉽지 않죠. 토스에는 여러분의 고민한 내용이 남긴 GitHub 저장소 링크 ...","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/ipd-tcs/toss_core/live/e813a909-42ab-461c-bcec-f934404747a7/bg.jpg","imageType":"썸네일 이미지"},"relatedPostConfig":{"id":6399,"relatedPosts":[{"id":33231,"updatedTime":"2025-08-28T01:07:22+09:00","createdTime":"2025-01-24T17:09:36+09:00","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"title":"무엇이든 물어보세요 (feat. 프론트엔드 코드, 디렉토리 관리) | EP.10 캠프파이어 특집 상편","subtitle":"모닥불 10화 특집: 캠프파이어 에피소드 🔥\n이번 모닥불은 특별히 시청자 여러분과 함께하는 시간으로 준비했어요.\n\n사전에 접수된 시청자 여러분의 다양한 사연과 질문 그리고 코드 리뷰까지!\n지금 바로 확인해보세요!","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/photos/modakbul10-4.png","backgroundColor":null,"isFill":false,"imageAlt":null},"editor":{"id":2292,"name":"토스 프론트엔드 챕터","slug":"frontend-chapter","shortDescription":null,"description":"-","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":13,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"key":"firesidechat_frontend_10","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-01-24T15:00:00+09:00","commentBoard":null,"disclaimer":null},{"id":30427,"updatedTime":"2025-08-28T00:04:31+09:00","createdTime":"2024-09-25T15:49:34+09:00","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"title":"토스 개발자는 개발만 잘해도 될까 | EP.5 모닥불","subtitle":"토스에서 말하는 일 잘하는 개발자의 기준은 무엇일까요?\n\n토스증권 이정연, 최지민 님이 직접 전하는 \"일 잘하는 개발자란 바로 이런 것!\" 함께 들어보세요!","bottomButtonConfig":{"ctaType":"NONE","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":null,"landingUrl":null,"isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":null,"landingExternal":null},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/photos/%EB%AA%A8%EB%8B%A5%EB%B6%885%ED%99%94_1.png","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/photos/%EB%AA%A8%EB%8B%A5%EB%B6%885%ED%99%94_1.png","backgroundColor":null,"isFill":true,"imageAlt":null},"editor":{"id":2292,"name":"토스 프론트엔드 챕터","slug":"frontend-chapter","shortDescription":null,"description":"-","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":13,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"key":"firesidechat_frontend_5","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2024-09-25T18:44:00+09:00","commentBoard":null,"disclaimer":null},{"id":31643,"updatedTime":"2025-08-28T03:26:22+09:00","createdTime":"2024-11-14T17:12:31+09:00","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"title":"토스 프론트엔드 개발자들이 더 이상 문서를 찾지 않는 이유","subtitle":"토스 프론트엔드 팀은 이제 문서를 찾아 헤매지 않아요. 문서와 AI로 개발자의 질문에 바로 답변해주는 환경을 만들고 있거든요. 개발에만 온전히 집중할 수 있는 새로운 문서 시스템, 어떻게 만들었는지 알려드려요.","bottomButtonConfig":{"ctaType":"ONLY_BUTTON","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":"지원하기","landingUrl":"https://toss.im/career/job-detail?job_id=4397469003","isSearchBottomCta":false,"landingInExternalBrowser":true,"serviceId":null,"stockConfig":null,"landingScheme":"supertoss://web?url=https%3A%2F%2Ftoss.im%2Fcareer%2Fjob-detail%3Fjob_id%3D4397469003&external=true&clearHistory=true&swipeRefresh=true","landingExternal":"https://toss.im/career/job-detail?job_id=4397469003"},"coverConfig":{"coverType":"NONE","imageUrl":null,"videoUrl":null,"backgroundColor":null,"isFill":false,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts-content/cover-ai.png","backgroundColor":null,"isFill":true,"imageAlt":null},"editor":{"id":2373,"name":"한주연","slug":"juyeon-han","shortDescription":"토스 Technical Writer","description":".","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"key":"toss-frontend-ai-docs","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2024-11-15T16:46:00+09:00","commentBoard":null,"disclaimer":null}],"title":"함께 읽어보면 좋을 콘텐츠"},"editor":{"id":556,"name":"박서진","slug":"sojin-park","shortDescription":"토스 Head of Frontend","description":"토스에서 프론트엔드 엔지니어링 헤드로 일하고 있어요.","imageUrl":"https://static.toss.im/assets/toss-tech/sojin.jpg","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":11,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"\n안녕하세요, 토스 프론트엔드 엔지니어링 헤드 박서진입니다.\n토스에서 이력서 없이 \"GitHub 리포지토리 링크로 지원하기\" 메뉴가 열렸어요. 이력서 작성에 고민해보신 적이 있나요? 이력서를 다듬고 최신화하는 것이 쉽지 않죠. 토스에는 여러분의 고민한 내용이 남긴 GitHub 저장소 링크 하나만 제출하면 돼요. 저희 프론","fullDescription":"\n안녕하세요, 토스 프론트엔드 엔지니어링 헤드 박서진입니다.\n토스에서 이력서 없이 \"GitHub 리포지토리 링크로 지원하기\" 메뉴가 열렸어요. 이력서 작성에 고민해보신 적이 있나요? 이력서를 다듬고 최신화하는 것이 쉽지 않죠. 토스에는 여러분의 고민한 내용이 남긴 GitHub 저장소 링크 하나만 제출하면 돼요. 저희 프론트엔드 리더들은 오직 코드를 기준으로 평가할게요.\n새로운 전형은 2025년 5월 31일 23:59까지 열려 있어요. 이력서가 아니라 코드만으로 평가받고 싶으신 분은 이번 기회를 놓치지 마세요.\n\n이런 리포지토리를 찾아요\n토스가 중요하게 생각하는 요소들을 다음 “리포지토리 제출 가이드” 에 담았어요.\n리포지토리 제출 가이드\n모듈화 및 코드 품질을 지키기 위해 고민한 리포지토리면 좋아요. \n명확한 디렉토리 구조로 코드 파일을 찾고 수정하기 쉽도록 고민한 리포지토리면 좋아요.\nTypeScript를 정확하게 사용하기 위해 고민한 리포지토리면 좋아요.\n제품의 완성도(성능 또는 사용 경험)를 끌어올리기 위해 고민한 리포지토리면 좋아요.\n커밋이나 Pull Request를 읽기 쉽게 나눠서 협업을 쉽게 한 리포지토리면 좋아요.\n화려한 기술이나 코드 패턴보다는 본질적인 코드의 고민이 드러나는 리포지토리면 좋아요.\n프로젝트가 어떤 것을 구현하는지 알 수 있는 README가 있는 리포지토리가 좋아요.\n코드 품질, 모듈화, 디렉토리 구조\n토스는 프론트엔드 코드의 품질, 모듈화, 디렉토리 구조를 제일 중요하게 생각해요. 토스에서는 소스 코드가 하루에 수십 번 업데이트되고 있는 만큼, 수정하기 쉬운 코드를 작성하는 것이 필수예요. 이런 핵심적인 요소들은 Frontend Fundamentals의 “변경하기 쉬운 코드” 에서도 다루고 있어요.\n여러분의 리포지토리에 “변경하기 쉬운 코드”, “재사용하기 쉬운 모듈”, “소스 코드를 쉽게 찾을 수 있는 디렉토리 구조”에 대한 고민이 담겨 있다면, 자신 있게 공유해 보세요.\nTypeScript\n토스에서는 모든 코드베이스가 TypeScript로 작성되어 있어요. 코드를 실행하기 전에 오류를 미리 감지하기 위해서는, 함수나 컴포넌트의 입출력 형식을 정확하게 TypeScript로 표현하는 능력이 중요해요. \n여러분이 TypeScript 타입을 정확하고 엄격하게 작성하기 위해 노력한 경험이 있는 코드라면, 꼭 공유해 주세요.\n제품의 완성도: 성능 또는 사용자 경험\n토스는 플랫폼 기업으로서, 최고의 사용자 경험이 비즈니스의 핵심이에요. 모바일 제품은 네이티브 앱과 구별하기 어려운 정도를 목표로 완성도를 높이려고 노력하고 있어요. 데스크톱 제품은 DEUS 에디터처럼 성능이 중요한 제품들이 계속 등장하고 있어요.\n사용자가 로딩 화면을 오래 기다리지 않고, 화면이 끊기거나 부자연스럽게 느껴지지 않도록 고민한 코드가 있으면 보여 주세요.\n협업\n토스에서는 프론트엔드 개발자들이 “챕터” 라고 하는 직군을 이루어 서로의 코드를 리뷰하고 지식을 공유하며 협업하고 있어요. 코드 컨벤션을 지키고 함께 성장하는 개발 문화를 만들기 위해 협업 능력은 필수예요.\n다른 개발자와 효율적으로 협업하기 위해 Pull Request나 커밋의 단위, 커밋 메시지 등에 신경쓴 리포지토리가 있다면, 공유해 주세요.\n\n화려한 기술이나 코드 패턴은 중요하지 않아요\n최근 프론트엔드 생태계에는 새로운 기술과 코드 패턴이 계속 등장하고 있어요. TanStack의 라우터나 폼, 기능 분할 설계(FSD) 같은 새로운 패턴도 제안되고 있죠.\n하지만 토스 프론트엔드에서는 이런 새로운 기술이나 패턴을 아는지 여부를 중요하게 생각하지 않아요. 대신 수정하기 쉬운 코드에 대한 여러분만의 고민과 철학, 제품 완성도에 몰입해 본 경험, 다른 프론트엔드 개발자들과 효율적으로 협업할 수 있는 능력 같은 것들을 중요하게 보고 있어요.\n특정 기술의 사용 여부보다는, 여러분의 고민과 철학이 담긴 코드를 보여주세요.\n\n이런 부분은 주의해 주세요\n전체에게 공개되어 있는 리포지토리 링크를 공유해 주세요. 재직하고 있는 회사의 리포지토리처럼, 비공개로 개발하고 있는 리포지토리는 공유하지 마세요. \n\n토스 프론트엔드 챕터와 함께해요\n토스의 프론트엔드 개발자들은 단순히 비즈니스 요구사항을 구현해 내는 것을 넘어, 프론트엔드 기술이 회사의 승리 전략이 될 수 있도록 탁월한 프론트엔드 개발 역량을 갖추기 위해 노력하고 있어요.\n프론트엔드 기술에 대한 고민을 오픈 소스로 공개하며, 1년만에 1만 개 이상의 GitHub 스타와 NPM 기준 주간 수십만 회 이상의 다운로드를 기록했어요. Storybook, Ink와 같은 유명 오픈소스 프로젝트들에서도 토스의 라이브러리들을 채택하고 있어요.\n토스의 프론트엔드 개발환경을 연내에 공개하여, 더 넓은 프론트엔드 개발에 대해서도 함께 고민하려고 해요. (참고 아티클 1, 참고 아티클 2)\n좋은 프론트엔드 코드란 무엇일까? 이런 고민을 “Frontend Fundamentals” 라고 하는 프로젝트로 출범시켜, 1천명 이상의 개발자와 함께 소통하고 있어요.\n올해부터는 한국의 개발 컨퍼런스를 넘어 세계적인 컨퍼런스에 참여하며 프론트엔드 생태계에 지속적으로 기여하려고 해요.\n\n여러분의 코드로 지원해 보세요\n지금까지 프론트엔드 개발에 진심이었고, 앞으로 프론트엔드 개발을 회사의 승리 전략으로 만드는 여정에 함께하고 싶다면, 부담 없이 “이력서 없이 리포지토리 링크로 지원하기” 전형으로 지원해 보세요. \n여러분의 리포지토리 링크에서 보이는 열정과 고민의 깊이를 기대할게요.\n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":36230},{"id":34481,"updatedTime":"2025-08-28T01:45:18+09:00","createdTime":"2025-03-24T20:56:16+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"캐시를 적용하기 까지의 험난한 길 (TPS 1만 안정적으로 서비스하기)","subtitle":"TPS가 평균 1만, 최대 2만까지 늘어난 약관(terms) 서버에 안정적인 서비스 제공을 위해 캐시를 적용한 이야기를 들려드리려고 해요.","bottomButtonConfig":{"ctaType":"ONLY_BUTTON","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":"Server Developer로 지원하기","landingUrl":"https://toss.im/career/job-detail?job_id=4071141003&company=%ED%86%A0%EC%8A%A4%EB%B1%85%ED%81%AC&detailedPosition=Product","isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":"supertoss://web?url=https%3A%2F%2Ftoss.im%2Fcareer%2Fjob-detail%3Fjob_id%3D4071141003%26company%3D%25ED%2586%25A0%25EC%258A%25A4%25EB%25B1%2585%25ED%2581%25AC%26detailedPosition%3DProduct&external=true&clearHistory=true&swipeRefresh=true","landingExternal":"https://toss.im/career/job-detail?job_id=4071141003&company=%ED%86%A0%EC%8A%A4%EB%B1%85%ED%81%AC&detailedPosition=Product"},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/assets/finance-tips/cover-financial-tips-cache-data.jpg","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/assets/finance-tips/cover-financial-tips-cache-data.jpg","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"34481","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-03-31T11:32:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":34481,"title":null,"description":"TPS가 평균 1만, 최대 2만까지 늘어난 약관(terms) 서버에 안정적인 서비스 제공을 위해 캐시를 적용한 이야기를 들려드리려고 해요.","urlSlug":"34481","primaryKeyword":null,"relatedKeywords":[],"tags":[{"id":41784,"content":"Server","wordType":"TAG"}]},"openGraph":{"title":"캐시를 적용하기 까지의 험난한 길 (TPS 1만 안정적으로 서비스하기)","description":"TPS가 평균 1만, 최대 2만까지 늘어난 약관(terms) 서버에 안정적인 서비스 제공을 위해 캐시를 적용한 이야기를 들려드리려고 해요.","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/assets/finance-tips/cover-financial-tips-cache-data.jpg","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2285,"name":"김경윤","slug":"kyungyoonkim","shortDescription":"토스뱅크 Server Developer","description":"-","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":2,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요, 토스뱅크 Server Developer 김경윤 입니다.\n토스 커뮤니티, 그리고 토스뱅크에서는 하루에 수 백번의 라이브 배포가 일어나고 있으며 다양한 개선점과 신규 제품들이 빠르게 출시되고 있어요. 이렇게 많은 배포를 기반으로 토스뱅크가 성장하면서 토스뱅크를 이용하는 사용자도 많아졌는데요. 이로 인해서 TPS가","fullDescription":"안녕하세요, 토스뱅크 Server Developer 김경윤 입니다.\n토스 커뮤니티, 그리고 토스뱅크에서는 하루에 수 백번의 라이브 배포가 일어나고 있으며 다양한 개선점과 신규 제품들이 빠르게 출시되고 있어요. 이렇게 많은 배포를 기반으로 토스뱅크가 성장하면서 토스뱅크를 이용하는 사용자도 많아졌는데요. 이로 인해서 TPS가 평균 1만, 최대 2만까지 늘어난 약관(terms) 서버에 안정적인 서비스 제공을 위해 캐시를 적용한 이야기를 들려드리려고 해요.\nDatabase: 더 이상 버틸 수 없다!\n약관 서버는 사용자가 동의 또는 철회한 약관 및 동의서 동의 여부를 기록하고 조회할 수 있는 서비스예요. 사용자가 동의 그리고 철회하는 경우는 그렇게 많지 않지만, 동의 여부에 따라서 개인 정보를 제3자에게 제공해도 되는지, 토스뱅크가 사용해도 되는지 등 다양한 비지니스에서 약관 및 동의서 동의 여부를 확인해요. \n(앞으로는 ‘약관 및 동의서’를 간단히 ‘약관’이라고 부를게요.)\n\n\n어느 날, 토스뱅크에서 새로운 서비스를 배포하면서 TPS가 급증했고, 이로 인해 DB 조회량이 급증하여 DB 부하가 심각해졌었어요. 이 트래픽이 유지될 경우 다른 서비스에도 문제가 생길 수 있다고 판단했고, 급히 롤백을 진행하며 DB 부하를 줄일 방안을 고민하게 되었어요. 그 결과, 많은 분들이 알고 계신 ‘캐시’를 적용하기로 했지만, 막상 시도해 보니 생각보다 간단치 않았어요.\n\n캐시 적용은 보다 신중하게\n이 글을 읽으면서, “어? 그럼 Replication된 Database를 두고 부하를 분산하면 되는거 아니야?” 라고 생각할 수 있어요. 약관은 토스뱅크 고객의 개인정보와 밀접한 연관성이 있어요. 약관 동의 여부는 사용자의 정보를 특정 목적으로 이용해도 되는지, 제3자에게 공유가 되도 되는지 결정하는 기준이기 때문이에요. \n그래서 약관 동의 여부는 값이 DB에 Commit 되는 순간, 바로 다음 요청에 DB에 저장된 값이 정확하게 응답되어야해요. 이를 Strong Consistency라고 부르며, 데이터의 무결성을 보장하기 위해 필수적이에요. 만약, 잘못된 응답을 한 번이라도 발생하면, 고객이 약관을 철회한 이후에도 개인정보가 공유되는 등의 보안 문제가 발생할 수 있어요. 따라서 데이터 신뢰성과 정확성을 보장하기 위해 Replication Database는 사용하지 않기로 했어요. Replication 구조에서는 복제 지연(Replication Delay)이 발생할 가능성이 있기 때문이에요. 대신, Strong Consistency를 유지하면서도 빠르게 조회가 가능한 Redis Cache를 활용해 고객의 약관 동의 상태를 안전하게 관리하기로 결정했어요.\n복제 지연(Replication Delay)?\n\n주 DB(Primary)와 보조 DB(Replica) 간의 데이터 동기화가 지연되는 현상\n\n이러한 방식으로 캐시를 적용했어요!\n\n약관 서버는 대부분 조회성으로 캐시를 접근하므로, DB의 정보가 자주 변경되지 않고, 대부분의 케이스는 Cache Hit를 하기 때문에, Look-aside 전략을 사용했어요. Look-aside 전략은 캐시에 원하는 데이터가 있는지 먼저 확인하고, 데이터가 없다면 DB에 접근한 후에 캐시에 저장하고 응답하는 방식이예요. 만약 DB 정보가 자주 변경된다면 다른 방식을 고민해야해요.\n\n@Component\nclass TermsAgreementEntityListener {\n private val eventPublisher: ApplicationEventPublisher by lazy {\n SpringContext.context\n }\n\n @PostUpdate\n @PostRemove\n @PostPersist\n fun postProcess(termsAgreement: TermsAgreement) {\n eventPublisher.publishEvent(\n\t StrongConsistencyCacheEvictEvent.of(\n termsAgreement = termsAgreement,\n\t )\n )\n }\n}\n\n@Component\nclass StrongConsistencyCacheEvictListener(\n private val strongConsistencyCacheService: StrongConsistencyCacheService,\n) {\n @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)\n fun listen(event: StrongConsistencyCacheEvictEvent) {\n strongConsistencyCacheService.evict(\n // ...\n )\n }\n}\n캐시 만료처리는 Spring의 @EntityListener와 @TransactionalEventListener 를 사용해서, DB에 Commit된 이후에 캐시가 만료되도록 했어요. DB에 Commit 전에 만료처리를 한다면, 다른 요청에서 Commit 전 데이터를 다시 캐시에 적재하는 아래와 같은 케이스가 발생할 수 있기 때문이에요.\n\n[과거 버전이 다시 적재되는 케이스]\nA Thread: 약관 동의 여부가 변경되어, Entity Version이 1에서 2로 올라감\nA Thread: Entity Version 1 캐시가 Evict 처리 됨 (아직 Commit 전)\nB Thread: Cache Miss로 Database에서 ⚠️ Entity Version 1을 다시 Cache에 적재함 ⚠️\nA Thread: Entity Version 2 Commit\nC Thread: Cache Hit로 ⚠️ 잘못된 Entity Version 1을 응답함 ⚠️\n\n이렇게 보면, 완벽한 것 같지만, @TransactionalEventListener 가 AFTER_COMMIT 으로 설정되어 있어, Cache Evict 처리가 실패해도, 이미 Commit 된 상태이기 때문에 Transaction이 Rollback 되지 않는 문제가 있어요. 그러면, 과거 캐시 버전이 지속적으로 응답되는 문제가 있죠. \n\n/* Strong Consistency Cache 서비스 */\n@Service\n@CircuitBreaker(name = ResilienceConfiguration.REDIS_CIRCUIT_BREAKER)\nclass StrongConsistencyCacheService\n\n/* Circuit Breaker 설정 */\n@Bean\nfun redisCircuitBreaker(registry: CircuitBreakerRegistry): CircuitBreaker {\n val circuitBreaker = registry.circuitBreaker(\n REDIS_CIRCUIT_BREAKER,\n circuitBreakerConfig()\n )\n\n circuitBreaker.eventPublisher.onError { error: CircuitBreakerOnErrorEvent ->\n // 하나의 오류라도 발생하면, 즉시 Force Open\n circuitBreaker.transitionToForcedOpenState()\n }\n\n return circuitBreaker\n}\n\n/* Cache Get 하는 메서드 */\nfun getOrElse(\n key: String,\n orElseFunc: () -> T?,\n): T? {\n val value: T? = try {\n\t\t // [1] - Cache Get 도중에 Circuit이 걸려서 Exception 발생\n strongConsistencyCacheService.get(\n\t\t\t\t\t\tkey = key,\n )\n } catch (ex: Exception) {\n\t\t // [2] - Circuit이 열려 있으면?\n if (redisCircuitBreaker.state.isOpened()) {\n\t\t // [3] - Database 기준으로 리턴!\n return orElseFunc()\n } else {\n\t\t\t\t\t\tthrow e \n }\n }\n \n // ...\n}\n그러한 문제를 해결하기 위해서, Circuit Breaker를 활용했어요. 만약, Cache Evict을 실패하면, Circuit을 Force Open 해서 자동으로 닫히지 않도록 하고, Cache Get할 때 Circuit이 Open 되어있다면, 모든 트래픽은 바로 Database를 조회하도록 하여, 잘못된 캐시가 응답되지 않도록 방어해두었어요. 이러한 방법은 Database에 큰 부하가 부담될 수 있지만, 잘못된 약관 동의 상태가 응답되어 문제가 발생되는 것보다, Database에 부하를 주고 빠르게 캐시에 대한 문제를 파악 및 해결하는 것이 맞다고 생각해서에요. 아직 이러한 경우를 만난 적이 없지만, 문제 발생 시 빠르게 확인, 해결할 수 있도록 상시 모니터링 중입니다!\nCircuit Breaker?\n\n주로 MSA 구조로된 서비스에서 서비스 간의 장애 전파를 미리 차단하고자 사용하는 기술\nCircuit Breaker에 대해 자세히 설명되어 있는 글을 소개드려요.\n이렇게 열심히 생각했지만 현실은…?\n그럼 Strong Consistency를 잘 지키고 있는지 확인을 해야 하는데요. 그러기 위해서 서버에는 캐시를 적용했지만, 응답은 항상 DB에 저장된 데이터를 응답 하도록하고 DB와 캐시 데이터를 비교해서 확인했어요. 열심히 준비했기 때문에 한 번에 테스트를 통과할 줄 알았지만 언제나 그렇듯, 아래와 같은 문제를 만났어요.\n0.003초 차이로 발생하는 불일치 케이스\n[문제 과정]\nA Thread - 약관 동의 발생\nA Thread - TermsAgreement 값이 변경되어서, ApplicationEvent 발행\nA Thread - 약관 동의 여부 변경 Kafka Event Produce\nA Thread - TermsAgreement가 DB에 Commit 됨\nB Thread - 약관 동의 여부 변경 Kafka Event Consume\nB Thread - 약관 동의 여부 조회시 캐시로부터 ⚠️ 이전 Entity Version 조회 됨 ⚠️ \nA Thread - AFTER_COMMIT 설정이 되어있어, 이때 Cache Evict 됨\n\nA Thread에서 Commit 이후, Cache를 Evict하는 그 0.003초 사이에 Kafka Event를 Consume한 곳에서 잘못된 캐시를 조회한 문제를 발견했어요. 이 케이스는 생각보다 간단히 해결할 수 있었어요. Kafka Event를 Cache Evict 처리 이후에 발행하도록 하면 되죠.\n\n/* Strong Consistency Cache Evict Listener */\n@Component\nclass StrongConsistencyCacheEvictListener(\n private val strongConsistencyCacheService: StrongConsistencyCacheService,\n) {\n @Order(Ordered.LOWEST_PRECEDENCE - 1)\n @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)\n fun listen(event: StrongConsistencyCacheEvictEvent)\n}\n\n/* @TransactionalEventListener와 동일한 역할을 하는 메서드 */\nfun doActionAfterCommitIfTransactionExist(order: Int = Ordered.LOWEST_PRECEDENCE, action: () -> Unit) {\n if (TransactionSynchronizationManager.isSynchronizationActive()) {\n TransactionSynchronizationManager.registerSynchronization(object : TransactionSynchronization {\n override fun afterCommit() {\n action()\n }\n\n override fun getOrder(): Int {\n return order\n }\n })\n } else {\n action()\n }\n}\n\n/* Kafka Event Produce 하는 부분 */\ndoActionAfterCommitIfTransactionExist {\n tossKafkaTemplate.send(\n topic = termsAgreementChangeTopic,\n key = termsAgreement.userId.toString(),\n value = termsAgreement,\n )\n}\nCache Evict과 비슷한 방식으로, Database Commit 이후에 처리되도록 TransactionSynchronizationManager를 활용했어요. 이때, Cache Evict과 Kafka Event Produce가 Commit 이후에 발생하도록 되어있으므로, 반드시 Cache Evict 이후에 Kafka Event Produce가 되도록 @Order와 TransactionSynchronization Interface의 getOrder메서드를 Override 하여 순서를 지정하여 처리 순서를 보장되도록 했어요. 자, 이제 그러면 아래와 같이 처리되므로 문제가 해결될거예요.\n\n[문제 해결 후 과정]\nA Thread - 약관 동의 발생\nA Thread - TermsAgreement 값이 변경되어서, ApplicationEvent 발행\nA Thread - TermsAgreement가 DB에 Commit 됨\nA Thread - AFTER_COMMIT 설정이 되어있어, 이때 Cache Evict 됨\nA Thread - 약관 동의 여부 변경 Kafka Event Produce\nB Thread - 약관 동의 여부 변경 Kafka Event Consume\nB Thread - 약관 동의 여부 조회시 캐시로부터 변경 후 Entity Version이 조회 됨\n그래도 Commit 이후 Cache Evict 처리 되기전에 조회하면…?\nKafka Event가 아니더라도, 발생할 확률은 엄청나게 낮지만, 여전히 Cache Evict 되기 전에 사용자의 요청이 들어온다면, 발생할 수 있어요. 이 경우는 코드로 어떻게든 해결할 수 있지만, 정책으로 해결했어요. “정책??” 이라는 생각이 잠깐 드실 거예요. 다시 처음으로 가보면, 우리는 아래와 같은 목표를 가졌어요.\n약관 동의 여부는 값이 DB에 Commit 되는 순간, 바로 다음 요청에 DB에 저장된 값이 응답되어야 한다.\n중요한 포인트는 “바로 다음 요청에 DB에 저장된 값이 응답되어야 한다” 입니다. @TransactionalEventListener 로 전달된 이벤트가 모두 처리되기 전에는 아직 API 응답을 하기 전 상태예요. 즉, 약관 동의 또는 철회 요청이 아직 완벽히 처리가 되기 전인 상태입니다. 그래서, Cache Evict 처리 되기 전은 아직 API가 처리 중인 상태인거죠! 그래서, 약관 서버는 아래와 같은 정책을 최종적으로 가지게 됩니다.\n약관 동의 여부는 약관 동의 또는 철회 요청 API 처리가 완료된 순간, 바로 다음 요청에 DB에 저장된 값이 응답되어야 한다.\n이러면, 제가 생각했던 문제가 더 이상 문제가 아니게 되었고, 코드를 작성하는 저와 제품을 담당하는 PO 모두 행복하게 약관을 서비스할 수 있게 되었어요!\n캐시를 적용하면서 느낀점\nExecution Over Perfection (완벽해지려 하기보다 실행에 집중하라)\n토스 커뮤니티의 여러 Core Value 중 하나인데요. 사실 매우 중요한 시스템 중 하나이기 때문에, 캐시를 적용하기 전에 완벽해지기 위해 Legal, Compliance 등 다양한 부분들을 먼저 검토하고 어떤 문제가 발생할지에 대해 다양한 방면을 고민하느라 캐시를 적용하는데 많은 시간이 들었던 것 같아요. 만약 Legal, Compliance 검토 이후 정책을 바로 세우고 캐시를 적용하여 모니터링해가며 만났던 문제들을 하나씩 해결해 나간다면 좀 더 빠르게 적용할 수 있었지 않을까 생각이 들었어요.\n코드로 해결할 수 있지만, 정책을 조금만 틀면 더 쉽게 해결할 수 있다\n프로그래머는 모든 것을 코드로 해결하려고 하면 안된다고 개인적으로 생각해요. 다양한 문제들이 존재할 때, 코드보다 더 쉬운 방법이 어딘가에는 존재할거에요. 이번에 말씀드린 문제를 해결한 과정은 정말 짧아 보이지만, 그 전에 수 많은 코드를 작성하고, 지웠고, 방법들을 고민했었어요. 결국 정책을 수정하여 코드보다 간단히 해결할 수 있었어요.\n마무리\n지금은 DB에 큰 부하 없이, 최대 2만 TPS 트래픽을 든든하게 버텨주는 서비스가 되었어요. 최대 2만 TPS의 트래픽은 사실, 한 번 사용자의 요청에 MSA 서비스들이 여러번 호출해서 수치가 높게 보이는 부분도 있는데요? 이런 불필요한 트래픽을 줄이기 위해, Netflix의 Passport와 비슷한 개념인, TermsPassport 와 같은 기술도 고민하고 있어요. 아직은 트래픽이 그렇게 높지 않아 적용을 하지 않지만, 만약 적용한다면 추후에 다시 글로 찾아뵐께요! \n","isDisplayingFeedback":true,"quizzes":[],"opinionForm":null,"viewCount":58051},{"id":34479,"updatedTime":"2025-08-28T00:04:29+09:00","createdTime":"2025-03-24T20:56:12+09:00","category":"개발","categories":[{"name":"개발","id":1024,"slug":"tech","parentId":null,"iconUrl":""}],"series":null,"seriesSlug":null,"title":"React Native에서 타입 안전한 파일 기반 라우팅 구현하기","subtitle":"오늘은 토스 자체 React Native 프레임워크 Granite이 어떻게 파일 기반 라우팅의 문제를 해결했는지 소개해드릴게요.","bottomButtonConfig":{"ctaType":"ONLY_BUTTON","imageUrl":null,"imageAlt":null,"title":null,"description":null,"ctaName":"FE Platform Engineer로 지원하기","landingUrl":"https://toss.im/career/job-detail?job_id=4397469003&company=%ED%86%A0%EC%8A%A4&detailedPosition=%EA%B3%B5%ED%86%B5","isSearchBottomCta":false,"landingInExternalBrowser":false,"serviceId":null,"stockConfig":null,"landingScheme":"supertoss://web?url=https%3A%2F%2Ftoss.im%2Fcareer%2Fjob-detail%3Fjob_id%3D4397469003%26company%3D%25ED%2586%25A0%25EC%258A%25A4%26detailedPosition%3D%25EA%25B3%25B5%25ED%2586%25B5&external=true&clearHistory=true&swipeRefresh=true","landingExternal":"https://toss.im/career/job-detail?job_id=4397469003&company=%ED%86%A0%EC%8A%A4&detailedPosition=%EA%B3%B5%ED%86%B5"},"coverConfig":{"coverType":"IMAGE","imageUrl":"https://static.toss.im/illusts-content/250525-thumbnail.png","videoUrl":null,"backgroundColor":null,"isFill":true,"imageAlt":null},"thumbnailConfig":{"imageUrl":"https://static.toss.im/illusts-content/250525-thumbnail.png","backgroundColor":null,"isFill":true,"imageAlt":null},"key":"rn-toss-bedrock","minAge":0,"isDisplaying":true,"isDisplayingPublishedTime":true,"workspaceId":15,"isPublished":true,"publishedTime":"2025-03-26T14:18:00+09:00","likeCount":0,"commentBoard":null,"relatedPostTitle":null,"relatedPosts":[],"disclaimer":null,"seoConfig":{"post":34479,"title":null,"description":"오늘은 토스 자체 React Native 프레임워크 Granite가 어떻게 파일 기반 라우팅의 문제를 해결했는지 소개해드릴게요.","urlSlug":"rn-toss-bedrock","primaryKeyword":null,"relatedKeywords":[],"tags":[{"id":41728,"content":"Frontend","wordType":"TAG"}]},"openGraph":{"title":"React Native에서 타입 안전한 파일 기반 라우팅 구현하기","description":"오늘은 토스 자체 React Native 프레임워크 Granite가 어떻게 파일 기반 라우팅의 문제를 해결했는지 소개해드릴게요.","backgroundColor":"#424242","imageAlt":null,"imageUrl":"https://static.toss.im/illusts-content/250525-thumbnail.png","imageType":"썸네일 이미지"},"relatedPostConfig":null,"editor":{"id":2489,"name":"강선규","slug":"gronxb","shortDescription":"토스 Frontend Platform Engineer","description":".","imageUrl":"https://static.toss.im/icons/png/4x/icon-toss-logo.png","url":null,"facebook":null,"twitter":null,"instagram":null,"postCount":1,"ogConfig":null,"seoConfig":null,"priority":1000,"isDisplaying":false,"isHomeRecommendation":false},"disclaimerConfig":null,"shortDescription":"안녕하세요. React Native Framework Team에 속한 Frontend Platform Engineer 강선규입니다. 오늘 소개해 드릴 이야기는 토스에서 만드는 React Native Framework와 그 기능에 관한 이야기에요.\nGranite이란?\n토스는 이전 글 토스가 꿈꾸는 React Native 기","fullDescription":"안녕하세요. React Native Framework Team에 속한 Frontend Platform Engineer 강선규입니다. 오늘 소개해 드릴 이야기는 토스에서 만드는 React Native Framework와 그 기능에 관한 이야기에요.\nGranite이란?\n토스는 이전 글 토스가 꿈꾸는 React Native 기술의 미래에서 자체적인 React Native 프레임워크를 개발한다고 공개했어요. 이 글을 통해서 해당 프레임워크, Granite을 처음 공개해요.\nGranite은 React Native 프레임워크로, 단단한 화강암을 의미하는 이름처럼 프로젝트 개발에 견고한 기초를 제공해요. Granite은 안정적이고 신뢰할 수 있는 구조를 바탕으로, 다양한 플랫폼에서 일관된 성능과 사용자 경험을 제공해요. 아직은 토스 내부 및 일부 협력사만 사용할 수 있지만, 추후에 공개를 목표로 오픈소스를 목표로 하고 있어요. (5월 29일자로 Granite는 외부 공개 되었어요🎉 https://github.com/toss/granite)\n기존 React Native 생태계에는 이미 Expo 같은 프레임워크가 존재하며, expo-router는 파일 기반 라우팅(File-Based Routing)을 사용해 화면을 정의합니다. Granite 역시 이와 유사하게 파일 기반 라우팅을 채택했으며, 이는 react-navigation v6를 기반으로 합니다. \n오늘은 토스 자체 React Native 프레임워크 Granite이 어떻게 파일 기반 라우팅의 문제를 해결했는지 소개해드릴게요.\n기존 파일 기반 라우팅의 문제점\n기존의 Granite 파일 기반 라우팅은 React Navigation을 추상화한 형태로, pages 폴더에 컴포넌트를 만들고 export default로 화면을 자동 등록하는 방식이었어요.\n예제 코드:\nexport default function Page() {\n const params = useRoute().params;\n \n return Hello {params.name};\n}\n하지만 이 방식은 화면 간 이동할 때 필요한 파라미터의 타입을 정의하기 어렵다는 문제가 있었어요. 그 결과, 어떤 파라미터가 필요한지 명확하게 알기 힘들었어요.\n\n1. Type-Safe Routing을 향한 발전\n이런 문제 때문에 최근 웹 프론트엔드에서는 tanstack router처럼 타입 안정성(Type-Safety)을 핵심으로 하는 라우터 프레임워크가 인기를 끌고 있어요.\nGranite도 기존 방식의 한계를 보완하기 위해 tanstack router의 방식에서 영감을 받아 Type-Safe한 파일 기반 라우팅을 도입했어요.\n이 방식은 co-location 원칙을 적용해서 각 화면의 타입을 같은 위치에서 정의하도록 했어요. 덕분에 더 명확한 개발 경험을 제공할 수 있어요.\n개선된 방식 예시\nimport React from 'react';\nimport { View, Text } from 'react-native';\nimport { createRoute } from '@granite-js/react-native';\nimport { z } from 'zod';\n\n// 라우트 정의\nexport const Route = createRoute('/page-a', {\n component: Page,\n validateParams: (params) => \n z.object({ name: z.string() }).parse(params), // 파라미터 검증 및 타입 추론\n});\n\n// 화면 컴포넌트\nfunction Page() {\n const params = Route.useParams(); // { name: string }으로 자동 추론됨\n return (\n \n Hello, {params.name}!\n \n );\n}\n이 방식에서는 validateParams로 파라미터를 검증하고, 그 결과를 자동으로 추론해서 params 타입으로 활용할 수 있어요. 그래서 라우팅이 더 명확하고 안전해졌어요.\n기존에는 export default를 기준으로 페이지가 등록됐지만, 이제는 export Route의 component 속성을 기준으로 페이지가 등록돼요.\n또한, validateParams를 활용해 각 화면의 타입을 명확하게 정의할 수 있도록 개선됐어요.\n🚩 useParams 내부 구현\n화면의 파라미터는 일반적으로 react-navigation의 useRoute().params 를 통해 가져올 수 있어요.\nGranite에서는 이를 활용하여 라우팅 로직과 독립적인 useParams를 별도로 정의하고, 해당 훅을 createRoute에 연결하는 방식을 사용했어요.\n실제 구현은 복잡할 수 있지만, 이해를 돕기 위해 간소화된 코드로 설명할게요.\n✅ 1. 독립적인 useParams 구현하기\nimport { useRoute } from \"@react-navigation/native\";\n\nfunction useParams() {\n return useRoute().params;\n}\n이렇게 만든 useParams는 현재 활성화된 라우트의 파라미터만 가져오며, 아직 타입 안정성은 없어요.\n✅ 2. createRoute에 useParams를 연결하기\n이제 위에서 만든 useParams를 createRoute의 반환값에 넣고, validateParams를 통해 타입 추론을 추가했어요.\nexport interface RouteOptions> {\n validateParams?: (params: Readonly

아티클 시리즈