Web3.py v6에서 v7으로의 마이그레이션을 AST와 AI로 자동화한 방법

Source: Dev.to

Web3.py v7 은 일반적인 의존성 업그레이드보다 훨씬 고통스러운 마이그레이션 문제를 도입했습니다. 미들웨어 아키텍처, 프로바이더 이름, 예외 임포트, 네임스페이스 사용 방식이 바뀌어, 기계적으로 마이그레이션하면 프로덕션 코드가 쉽게 깨질 수 있습니다.

저는 Web3.py v7 Zero‑BS Migrator 를 만들어서 하이브리드 접근 방식으로 업그레이드를 자동화했습니다: 정적 분석이 가능한 변경은 결정론적 AST 변환으로, 순수 구문 규칙만으로 안전하게 변환할 수 없는 미들웨어 패턴은 제한된 AI 재작성 레이어를 사용했습니다.

프로젝트 링크

• DoraHacks 제출:
• 데모 영상:
• GitHub PR:
• 라이브 앱:

문제점

Web3.py v7 에서 가장 큰 파괴적 변화는 함수형 미들웨어에서 클래스 기반 미들웨어로 전환된 점입니다. 이는 많은 기존 코드베이스가 단순한 검색‑및‑치환 로직만으로는 업그레이드될 수 없다는 것을 의미합니다. 미들웨어에는 종종 커스텀 로직과 프로젝트 특화 동작이 포함되어 있기 때문입니다.

마이그레이션에는 WebsocketProviderV2 → WebSocketProvider, .ws → .socket, 예외 및 AttributeDict 관련 업데이트와 같은 변경도 포함됩니다. 실제 코드베이스에서는 이러한 변경이 반복적이고 놓치기 쉬우며, 수동 검토에 많은 비용이 듭니다.

설계

레이어 1: 결정론적 AST 변환

첫 번째 레이어는 Tree‑Sitter 기반 AST 변환을 사용해 결정론적으로 변환 가능한 마이그레이션 패턴을 처리합니다. 여기에는 프로바이더 이름 변경, 예외 임포트 조정, AttributeDict 변경, .ws → .socket 같은 네임스페이스 업데이트가 포함됩니다.

구문만으로 변환이 증명될 수 있다면, AI 대신 결정론적 규칙으로 처리해야 합니다.

레이어 2: 미들웨어 마이그레이션을 위한 범위 제한 AI

두 번째 레이어는 함수형 미들웨어에만 적용됩니다. 결정론적 변환만으로는 충분하지 않은 경우에만 사용됩니다. 도구는 샌드박스화된 NVIDIA NIM Llama‑3‑70B 재작성 엔진을 사용해 전체 파일이 아니라 해당 함수 노드에만 적용합니다.

이렇게 하면 AI 구성 요소가 실제 가치를 제공하는 영역에만 제한되고, 컨텍스트 주입, 들여쓰기 추적, 재시도 로직, 폐기 처리와 같은 안전 제어가 적용돼 실무에서 재작성 기능을 사용할 수 있게 됩니다.

결과

• 120개 파일 테스트 스위트
• 총 142개 패턴 발견
• 130개 자동 변환
• 91.5 % 자동화 커버리지
• 0 false positive
• 98.59 평가 점수

핵심 교훈은 간단합니다: 가능한 한 결정론적 변환을 사용하고, 마이그레이션이 구조적(architectural)일 때만 AI를 활용하라는 것입니다. 마이그레이션 도구가 이 경계를 존중한다면 빠르고 신뢰할 수 있습니다.

실제로, Web3.py v6 에서 v7 로 업그레이드하는 팀은 대부분의 마이그레이션을 빠르게 자동화하면서, 커스텀 미들웨어는 통제되고 검토 가능한 재작성 단계로 처리할 수 있습니다.

데모 및 링크

• DoraHacks 제출:
• 데모 영상:
• GitHub PR:
• 라이브 앱:

마무리 메모

이 도구를 만들면서 얻은 가장 큰 교훈은 마이그레이션 툴이 결정론적 코드 변환과 구조적 판단을 분리할 때 가장 효과적이라는 점입니다. Web3.py v7 은 왜 이러한 구분이 중요한지를 보여주는 좋은 사례입니다: 일부 파괴적 변화는 단순 재작성으로 해결되지만, 다른 변화는 의도에 대한 깊은 이해가 필요합니다. 마이그레이션 툴이 이 경계를 존중한다면 빠르고 신뢰할 수 있는 결과를 제공할 수 있습니다.