Streams API 심화
Streams API의 고급 사용법과 성능 최적화를 다룹니다.
학습 목표#
- Streams의 내부 동작 이해
- DOM ID 전략
- 커스텀 템플릿 사용
- 성능 최적화 기법
- 트러블슈팅
Streams vs 일반 렌더링#
일반 렌더링의 문제#
class BadExample(Component):
items: list = [] # 1000개 아이템
async def add_item(self, item):
self.items.append(item)
# 전체 리스트 HTML 다시 렌더링 후 전송
문제점:
- 매번 전체 HTML 생성 (~50KB)
- 대역폭 낭비
- DOM 전체 업데이트
- 메모리 사용량 증가
Streams의 해결책#
class GoodExample(Component):
items: list = []
async def add_item(self, item):
# 새 아이템 HTML만 전송 (~500B)
await self.stream_insert("items", item)
장점:
- 변경된 부분만 전송
- 최소한의 DOM 업데이트
- 메모리 효율적
- 빠른 응답
QuerySet은 그대로 넘긴다#
stream()은 QuerySet이나 async iterable을 async for로 읽는다. 핸들러는 이벤트 루프 위에서 돌고,
거기서 QuerySet을 동기로 반복하면 Django가 SynchronousOnlyOperation으로 막는다. 그래서 목록으로
미리 바꿀 필요가 없다.
async def joined(self):
await self.stream("items", Item.objects.order_by("-created_at")[:100])
직접 만든 동기 제너레이터는 그대로 반복된다. 그 안에서 ORM을 부르면 막힌다.
DOM ID 전략#
기본 규칙#
Stream 아이템의 DOM ID는 {stream_name}-{pk} 형식입니다:
<li id="messages-123">...</li>
<li id="messages-124">...</li>
커스텀 DOM ID#
함수로 지정#
async def joined(self):
await self.stream(
"items",
items,
dom_id=lambda item: f"item-{item.uuid}"
)
UUID 사용#
stream()과 stream_insert()는 같은 dom_id를 써야 한다. 삽입과 초기 로딩이 다른 규칙으로 id를 만들면
같은 항목이 두 번 들어간다. 헬퍼 하나로 묶어 둔다. 이름은 _로 시작해야 한다 — stream_insert를
오버라이드하면 자기 자신을 부르게 된다.
async def _insert(self, name, item, **kwargs):
await self.stream_insert(
name,
item,
dom_id=lambda i: f"{name}-{i.uuid}",
**kwargs,
)
같은 페이지의 여러 스트림#
스트림 이름은 컴포넌트 안에서만 고유하면 된다. 클라이언트는 wire-stream 컨테이너를 스트림을 보낸 컴포넌트의
요소 안에서 찾고, 그 안에 중첩된 컴포넌트의 같은 이름 컨테이너보다 자기 것을 먼저 고른다. 그래서 같은 컴포넌트를
두 번 놓아 둘 다 "items"를 써도 각자의 목록에 들어간다.
새로 나타난 컴포넌트(부모의 렌더가 처음 그린 LiveComponent 등)가 joined()에서 보낸 스트림도 그 목록에 들어간다.
그 연산은 컴포넌트를 처음 그리는 렌더 바로 뒤에 오지만, 페이지는 렌더를 다음 애니메이션 프레임에 패치하므로
연산이 도착한 순간에는 컨테이너가 아직 없다. 컨테이너를 못 찾은 연산은 다음 프레임(이미 예약된 패치 뒤)까지
기다렸다가 다시 찾는다. 같은 컴포넌트가 그 뒤에 보낸 연산도 함께 기다려 서버가 보낸 순서를 지키고, 다른
컴포넌트의 연산은 기다리지 않고 바로 적용된다. push_js와 push_event도 같은 줄에 서므로 스트림 연산과의
순서도 지켜진다. 한 프레임 뒤에도 없으면(컴포넌트가 그 사이 떠났으면) 경고를 남기고 버린다. 그래서 보류한
연산은 그 컴포넌트가 다음 프레임까지 보낸 것뿐이다 — 프레임이 돌지 않는 백그라운드 탭에서도 다른 컴포넌트의
스트림이 쌓이지 않는다. 보류한 연산 하나가 실패하면(console.error) 그 연산만 빠지고 나머지는 적용된다.
항목의 id는 HTML id라 페이지에서 고유해야 하는 것은 그대로다. 기본값이 {스트림 이름}-{pk}이므로 같은 항목이
두 목록에 함께 나올 수 있으면 dom_id에 컴포넌트 id를 넣는다.
class XList(Component):
async def joined(self):
await self.stream(
"items",
[item async for item in Item.objects.all()],
dom_id=lambda item: f"{self.id}-item-{item.pk}",
)
커스텀 템플릿#
기본 템플릿 경로#
컴포넌트 템플릿 이름에 _item을 붙인 것이다. 스트림 이름과는 무관하다.
{컴포넌트 template_name에서 확장자를 뺀 것}_item.html
예: 컴포넌트의 template_name이 chat/x_chat.html이면 chat/x_chat_item.html. 한 컴포넌트에 스트림이
둘 이상이면 기본 경로를 함께 쓰게 되므로 template=으로 나눈다. 항목 템플릿의 컨텍스트 변수는 item이다.
명시적 템플릿 지정#
await self.stream(
"messages",
messages,
template="chat/custom_message.html"
)
await self.stream_insert(
"messages",
message,
template="chat/highlighted_message.html"
)
조건부 템플릿#
async def add_message(self, message):
template = (
"chat/system_message.html"
if message.is_system
else "chat/user_message.html"
)
await self.stream_insert("messages", message, template=template)
삽입 위치 제어#
at 파라미터#
| 값 | 동작 |
|---|---|
-1 (기본) |
끝에 추가 (append) |
0 |
처음에 추가 (prepend) |
n |
n번째 위치에 삽입 |
사용 예#
# 새 메시지를 끝에 추가
await self.stream_insert("messages", message, at=-1)
# 새 알림을 맨 위에 추가
await self.stream_insert("notifications", notif, at=0)
# 특정 위치에 삽입
await self.stream_insert("items", item, at=5)
이미 화면에 있는 항목이면 제자리 갱신#
stream_insert의 dom id가 이미 DOM에 있으면 at과 무관하게 그 자리에서 교체됩니다.
생성과 갱신을 한 갈래로 쓸 수 있습니다.
async def mutation(self, channel, action, instance):
if action == ModelAction.DELETED:
await self.stream_delete("items", f"items-{instance.pk}")
else:
# 새 항목이면 맨 위에, 이미 있는 항목이면 제자리 갱신
await self.stream_insert("items", instance, at=0)
화면에 없으면 넣지 않으려면 update_only=True를 줍니다. 목록의 일부만 불러온 페이지(무한 스크롤)에
고친 항목을 보낼 때입니다. 보통의 stream_insert는 없는 id를 at 자리에 새로 넣으므로, 그 페이지가 불러온
적 없는 오래된 항목이 목록 끝에 나타납니다.
async def save(self, pk: int, text: str):
# pk는 브라우저가 보낸 값이다: 이 사용자가 고칠 수 있는 항목인지 조회에서 다시 묻는다
item = await Item.objects.filter(pk=pk, owner=self.user.pk).afirst()
if item is None:
return
item.text = text
await item.asave()
# 보이는 페이지는 제자리에서 바꾸고, 없는 페이지는 아무것도 하지 않는다
await self.stream_insert("items", item, update_only=True)
누가 무엇을 고칠 수 있는가는 서버가 핸들러마다 다시 묻는다. 버튼을 숨겨도 이벤트는 손으로 만들 수 있다 —
chat_lv3의 _own_message가 작성자·방·멤버십을 한 곳에서 묻는다.
update_only는 vsn 10 이상의 클라이언트에만 간다. 그 전의 번들은 이 필드를 몰라 없는 항목을 at에 넣으므로,
서버가 그 연결에는 보내지 않는다. 롤링 배포 중 옛 JS로 열린 페이지는 다시 join할 때까지 고치기 전 내용을 보인다
(wire-protocol §7).
핸들러와 mutation() 양쪽에서 넣지 마세요. 모델을 구독하고 있으면 저장 신호가 자기
연결로도 돌아옵니다. 두 곳에서 넣으면 같은 항목이 두 번 들어갑니다 — 구독 중이라면
삽입은 mutation() 한 곳에서만 하고 핸들러는 저장만 합니다.
재렌더는 스트림을 지우지 않는다#
컴포넌트 템플릿은 빈 컨테이너만 렌더합니다. 그래서 wire-stream 컨테이너는 DOM 패치
대상에서 제외되고, 상태를 바꾼 뒤 다시 스트리밍하는 핸들러(필터·정렬 전환)가 정상 동작합니다.
async def set_filter(self, filter: str):
self.filter = filter # 재렌더가 일어나도
await self.stream("items", self.queryset) # 이 결과가 남는다
컨테이너 자체의 속성(class 등)은 이 때문에 서버 렌더로 갱신되지 않습니다. 컨테이너 속성을 바꿔야 한다면 바깥 엘리먼트에 두세요.
렌더가 컨테이너 앞에 새 요소를 그려도(새 LiveComponent, {% if %}로 나타난 다른 목록) 목록은 남습니다.
morph는 id가 없는 요소를 자리로 짝짓기 때문에, 그대로 두면 새 요소가 컨테이너 자리를 차지하고 컨테이너는
항목과 함께 지워졌습니다. 그래서 페이지는 패치하기 전에 렌더의 컨테이너에 화면의 컨테이너와 같은 id를 붙입니다.
템플릿이 컨테이너에 id를 달았으면 그 id를 쓰고, 없으면 wire-stream-{컴포넌트 id}-{스트림 이름}을 붙입니다.
그 id는 페이지에만 붙고 서버가 보내는 HTML은 그대로입니다.
성능 최적화#
1. 배치 삽입#
여러 아이템을 한 번에 추가:
# 비효율적: 항목마다 연산 하나, 프레임 하나
for item in items:
await self.stream_insert("items", item)
# 효율적 - 목록을 바꾸려면 stream()으로 리셋
await self.stream("items", items)
# 효율적 - 화면의 것을 두고 덧붙이려면 reset=False: 연산 하나, 프레임 하나
await self.stream("items", items, reset=False) # 끝에
await self.stream("items", newer, at=0, reset=False) # 맨 앞에
reset=False면 항목들이 at 자리에 주어진 순서대로 한 덩어리로 들어간다. at=0에 [a, b, c]를 넣으면
화면 맨 앞이 a, b, c 순서다(하나씩 stream_insert(at=0)하면 c, b, a가 된다). 이미 화면에 있는 id는 제자리에서
바뀐다. limit은 다 넣은 뒤 한 번 자른다. at=0이면 끝에서, 그 밖(끝에 붙이거나 가운데에 넣을 때)에는 앞에서
자른다. 빈 목록이면 아무것도 보내지 않는다.
읽어 붙일 때 stream_insert 반복보다 나은 점이 하나 더 있다. reset=False에 QuerySet을 그대로 넘기면 읽기 전부터
그 컴포넌트의 Broadcast 패치를 잡아 두고 삽입이 나간 뒤에 쓴다. 그래서 읽는 동안 다른 사람이 지우거나 고친 항목이
삽입에 덮여 되살아나지 않는다. stream_insert는 패치를 잡지 않으므로, 읽은 목록을 하나씩 넣으면 그 사이의 삭제·수정이
되돌려진다.
잡아 둔 패치는 핸들러가 끝나고 삽입이 쓰일 때 나간다. stream() 뒤에 오래 걸리는 일(외부 API 호출 등)이 있으면 그동안
이 컴포넌트에 오는 Broadcast가 화면에 나타나지 않고, 너무 많이 쌓이면 연결이 닫혀 다시 join한다. 그런 일은
start_async로 넘기거나 stream()을 핸들러 끝에 둔다
(Broadcast — 순서와 유실).
2. 초기 로딩 최적화#
async def joined(self):
# 최근 50개만 로드
messages = [m async for m in Message.objects.order_by('-id')[:50]]
await self.stream("messages", list(reversed(messages)))
async def load_more(self):
# 추가 로딩
older = await self._load_older()
for msg in older:
await self.stream_insert("messages", msg, at=0)
3. 스크롤 최적화#
async def add_message(self, message):
await self.stream_insert("messages", message)
# 부드러운 스크롤
await self.scroll_into_view(
f"messages-{message.pk}",
behavior="smooth",
block="end"
)
4. 불필요한 렌더링 방지#
async def add_item(self, item):
await self.stream_insert("items", item)
self.skip_render() # 컴포넌트 전체 렌더링 방지
5. 모두에게 같은 항목이면 Broadcast#
새 글을 피드를 연 모든 페이지에 넣을 때, 알림을 보내 연결마다 notification()에서 stream_insert()하면 같은 항목을
연결 수만큼 렌더합니다. Broadcast는 발행하는 곳에서 한 번 렌더하고, 각 연결은 그 결과에 자기 컴포넌트 id만 끼워
씁니다. 연결 1,000개에서 수백 ms가 수십 ms가 됩니다.
from wireview import Broadcast
class XFeed(Component):
class Meta:
template_name = "feed/x_feed.html"
subscriptions = {"feed"}
async def publish(self, text: str):
post = await Post.objects.acreate(text=text)
await Broadcast(XFeed, "feed").stream_insert("posts", post, at=0, limit=100).asend()
항목 템플릿은 item만 읽을 수 있습니다. 모두가 같은 HTML을 받으므로 this·user·request를 읽으면 오류가 납니다.
자세한 규칙은 Broadcast에 있습니다.
트러블슈팅#
아이템이 표시되지 않음#
-
wire-stream 속성 확인
<ul wire-stream="items"> <!-- 이름 일치 확인 --> -
DOM ID 확인 — 항목 템플릿에
id를 적지 않아도 된다. 클라이언트가dom_id(기본{name}-{item.pk})로 붙인다.pk가 없는 항목(dict 등)이면dom_id=를 넘겨야 한다. -
템플릿 경로 확인
- 기본은 컴포넌트 템플릿 이름 +
_item.html(예:chat/x_chat.html→chat/x_chat_item.html)
- 기본은 컴포넌트 템플릿 이름 +
순서가 잘못됨#
at 파라미터 확인:
# 최신이 위로
await self.stream_insert("items", item, at=0)
# 최신이 아래로
await self.stream_insert("items", item, at=-1)
메모리 누수#
화면에 남길 개수는 limit으로 정한다. 넘치면 클라이언트가 반대쪽 끝부터 지운다. 서버는 항목을 들고
있지 않으므로 컴포넌트 상태에 목록을 따로 둘 필요가 없다.
async def add_message(self, message):
# 최신 1000개만 화면에 남긴다
await self.stream_insert("messages", message, limit=1000)
무한 스크롤 (wire-viewport-top / wire-viewport-bottom)#
목록 아래(또는 위)에 둔 요소가 화면에 들어오면 그 속성에 적은 핸들러가 불린다. 아래로 스크롤하다
바닥 요소가 보이면 wire-viewport-bottom, 위로 스크롤하다 꼭대기 요소가 보이면 wire-viewport-top이다.
<ul wire-stream="rows"></ul>
<div wire-viewport-bottom="load_more">불러오는 중...</div>
async def load_more(self):
self.page += 1
# 한 페이지를 연산 하나로 붙인다
await self.stream("rows", Row.objects.all()[self.page * 20:(self.page + 1) * 20], reset=False)
스크롤 방향과 맞을 때만 불린다. 페이지를 열었을 때 이미 보이는 요소는 부르지 않지만, 요소가 화면 가운데를 이미 지나 있으면(목록이 짧을 때) 방향과 무관하게 부른다.
방향은 그 요소를 움직일 수 있는 모든 스크롤에서 본다. overflow-y가 auto(또는 scroll)인 조상들과 창 중
어느 하나라도 그 요소 쪽으로 움직였으면 그 방향이다. 채팅 목록처럼 자기 스크롤바가 있는 상자 안에 두면 창은
움직이지 않고 상자만 움직이고, 창으로 스크롤하는 페이지에서는 overflow-x: hidden만 둔 래퍼(계산된
overflow-y가 auto가 된다)가 움직이지 않고 창만 움직인다 — 둘 다 그대로 불린다. "가운데"는 그 요소의
스크롤 상자에서 잰다. overflow-y가 스크롤 값이고 실제로 넘치는(내용이 보이는 높이보다 큰) 가장 가까운
조상이 상자이고, 그런 조상이 없으면 창이다. 상자 중 창에 보이는 부분의 가운데다. flex-direction: column-reverse로 아래에서 위로 그리는
목록은 scrollTop이 0에서 시작해 위로 갈수록 음수가 되지만 "위는 더 작다"는 그대로다. 그런 목록에서는 DOM의
끝이 화면의 맨 위이므로, 위에 붙일 과거 항목은 at=-1로 넣는다(chat_lv3). 그 구분이 필요하면 핸들러가
_overran 인자를 받는다. 받지 않는 핸들러에는 넘어가지 않는다.
이 판단은 join이 끝난 뒤에 한다. joined()가 보낸 첫 페이지가 화면에 들어온 다음이다. 그 전에는
목록이 비어 바닥 요소가 늘 화면 위쪽에 있으므로, 목록이 길어도 한 페이지를 더 부르곤 했다(#112).
재연결 뒤에도 같다. 끊긴 연결의 판단은 그 연결과 함께 끝나고, 재연결의 joined가 새로 시작한다.
바인딩은 그것을 감싼 가장 가까운 컴포넌트의 것이다. LiveComponent 안의 wire-viewport-bottom은 그
LiveComponent의 핸들러를 부르고, 부모의 같은 이름 핸들러는 부르지 않는다. 중첩된 {% component %}
안의 것도 그 컴포넌트의 것이다. 부모의 렌더가 새로 그린 LiveComponent나 {% component %}도 자기
joined()가 보낸 첫 페이지가 들어온 뒤에 판단을 시작한다.
고급 패턴#
Virtual Scrolling 준비#
class XVirtualList(Component):
visible_items: list = []
scroll_top: int = 0
item_height: int = 50
async def on_scroll(self, scroll_top: int):
self.scroll_top = scroll_top
start = scroll_top // self.item_height
end = start + 20 # 화면에 20개
# 표시할 아이템만 로드
self.visible_items = await self._load_range(start, end)
드래그 앤 드롭 순서 변경#
async def reorder(self, item_id: int, new_index: int):
item = await Item.objects.aget(id=item_id)
# DB 순서 업데이트
await self._update_order(item, new_index)
# 스트림에서 제거 후 새 위치에 삽입
await self.stream_delete("items", item_id)
await self.stream_insert("items", item, at=new_index)