검색어 C++가 C와 공백 두 개로 바뀌거나, 태그 두 개 중 하나만 남는다면 URL을 만들고 읽는 경계를 확인하세요. 이 글은 검색·필터의 쿼리 문자열을 다룹니다. HTML 폼에서 필드 자체가 빠지는 문제는 FormData 수집 가이드, 바이트를 잘못 디코딩해 한글이 깨지는 문제는 문자 인코딩 가이드에서 먼저 분리할 수 있습니다.
처음 값이 달라지는 경계를 찾으세요
| 관찰 | 확인할 코드 | 판단 |
|---|---|---|
| q=C++를 읽었더니 뒤에 공백 두 개 | 문자열로 직접 쿼리를 붙였는가 | form-urlencoded의 + 해석을 받은 것 |
| C%2B%2B가 화면 값으로 남음 | set 이전에 encodeURIComponent를 적용했는가 | 인코딩 층을 한 번 더 만든 경우 확인 |
| tag 두 개가 한 개로 보임 | get·set·일반 객체 변환 사용 | 다중 값 정책과 맞는지 대조 |
| URL 글자 모양만 %20에서 +로 변함 | searchParams를 수정했는가 | 해석된 값이 같은지 먼저 비교 |
| 완전한 URL에서 q가 null | URLSearchParams에 전체 URL을 넘겼는가 | new URL(…).searchParams로 읽기 |
합성 검색어로 원래 값 → 직렬화한 query → 다시 읽은 값 → 서버가 파싱한 값을 순서대로 비교합니다. 운영 URL 전체에는 개인 정보나 인증 관련 값이 섞일 수 있으므로 재현 기록에는 민감한 값을 넣지 않습니다.
파싱할 문자열과 설정할 원문 값을 구분하세요
문자열 생성자는 이미 만들어진 쿼리를 해석합니다. 이때 +는 공백으로 읽히며 실제 더하기 문자는 %2B로 표현됩니다. 반대로 set·append나 값 쌍을 사용할 때는 인코딩하지 않은 원문을 넘깁니다. 키와 값 안의 &·=·#도 수동 연결 대신 직렬화에 맡깁니다.
const parsed = new URLSearchParams('q=C++');
console.log(JSON.stringify(parsed.get('q'))); // "C "
const made = new URLSearchParams();
made.set('q', 'C++');
console.log(made.toString()); // q=C%2B%2B
console.log(new URLSearchParams(made.toString()).get('q')); // C++
// 원문이 아니라 인코딩 결과를 값으로 넣으면 한 층 더 감싸집니다.
made.set('q', encodeURIComponent('C++'));
console.log(made.toString()); // q=C%252B%252B
decodeURIComponent를 파싱 결과에 다시 적용하는 식으로 덮어 고치지 마세요. 사용자가 검색한 원문이 문자 그대로 %2B일 수도 있습니다. 값이 원문인지 직렬화된 쿼리인지 함수 인자 계약으로 정하고, 정해진 경계에서 한 번씩 처리합니다.
단일 검색어와 여러 태그의 계약을 나누세요
이 예제에서는 q는 한 값, tag는 순서를 유지하는 여러 값입니다. 같은 태그를 두 번 입력해도 보존합니다. 중복 제거가 필요한 서비스라면 서버와 같은 규칙으로 따로 정하세요. get은 첫 값만 읽고 getAll은 전체 값을 읽습니다. set은 같은 이름의 기존 값들을 대체하므로 태그를 반복해서 set하면 마지막 설정만 남습니다. 빈 키의 값과 없는 키는 get 결과가 빈 문자열과 null로 다릅니다. 값 없는 bare 키와 bare=는 같은 빈 값으로 해석됩니다.
const params = new URL('https://example.invalid/apps/?tag=web&tag=android')
.searchParams;
console.log(params.get('tag')); // web
console.log(params.getAll('tag')); // ['web', 'android']
// 단일 키로 취급할 필드는 입력 단계에서 중복 여부도 확인합니다.
if (params.getAll('q').length > 1) {
throw new Error('이 예제에서는 검색어 중복을 허용하지 않습니다.');
}
getAll로 읽었다고 유효성 검사가 끝난 것은 아닙니다. 허용 태그·최대 개수·페이지 범위·중복 키의 처리 방식을 API 계약으로 정하세요. 배열을 문자열 하나로 암묵 변환하거나 모든 쿼리를 일반 객체로 바꿔 다중 값이 사라지게 하지 않습니다.
새 검색 URL을 만드는 완전한 함수
아래 JavaScript 함수는 새 예시 URL을 만들기만 합니다. fetch·화면 이동·서버 저장을 하지 않습니다. q는 앞뒤 공백을 제거한 코드 포인트 1~120개, page는 정수 1~100, tag는 허용 목록의 최대 5개라는 이 예제의 정책을 가정합니다. 코드 포인트 수는 보이는 글자 수·UTF-8 바이트 수와 다르며 URL 표준의 공통 제한도 아닙니다. 실제 프로젝트의 계약으로 바꾸세요.
function buildSearchUrl({ q, tags = [], page = 1 }) {
// 이 예제의 검색 계약: 앞뒤 공백 제거, 코드 포인트 1~120개.
if (typeof q !== 'string') throw new TypeError('q must be a string');
const query = q.trim();
if ([...query].length < 1 || [...query].length > 120) {
throw new RangeError('q length is outside the example contract');
}
const allowedTags = new Set(['web', 'android', 'desktop']);
if (!Array.isArray(tags) || tags.length > 5 ||
tags.some(tag => typeof tag !== 'string' || !allowedTags.has(tag))) {
throw new TypeError('invalid tags');
}
if (!Number.isInteger(page) || page < 1 || page > 100) {
throw new RangeError('invalid page');
}
// 새 URL 전용입니다. 기존 서명 URL을 재작성하는 함수가 아닙니다.
const url = new URL('https://example.invalid/apps/');
url.searchParams.set('q', query); // encodeURIComponent를 미리 적용하지 않음
for (const tag of tags) url.searchParams.append('tag', tag);
if (page !== 1) url.searchParams.set('page', String(page));
return url.href; // 문자열 생성만 수행하며 요청은 보내지 않음
}
buildSearchUrl({ q: ‘C++ 한글 & 도움말’, tags: [‘web’, ‘android’], page: 2 })로 만든 문자열을 new URL로 읽으면 q 원문, 태그 두 값, page=’2’를 확인할 수 있습니다. page=1은 예제의 기본값이므로 URL에서 생략합니다. example.invalid는 예제 주소이며 이 코드는 해당 주소에 요청하지 않습니다.
Node에서 직접 관찰한 결과와 시험하지 않은 범위
2026년 11월 2일 v24.22.1의 실제 URL·URLSearchParams 객체와 위 함수를 사용해 비교 검사 16건을 실행했습니다. 모의 URL 객체가 아닙니다. 아래는 그 실행에서 관찰한 대표 결과입니다.
| 입력·조작 | 관찰 결과 |
|---|---|
| q=C++ / q=C%2B%2B 파싱 | 각각 “C ” / “C++” |
| 원문 C++를 set / 미리 인코딩한 값을 set | q=C%2B%2B / q=C%252B%252B |
| flutter web 원문 직렬화·재파싱 | q=flutter+web, 읽은 값은 원문 |
| 한글과 &·=·?·# 포함 원문 | 직렬화 후 재파싱한 값 일치 |
| tag=web&tag=android | get은 web, getAll은 두 값, 객체 변환은 android만 남음 |
| 중복 tag에 set(‘tag’, ‘desktop’) | desktop 하나로 대체 |
| 없는 키 / empty= / bare | null / 빈 문자열 / 빈 문자열 |
| q=a%20~인 URL에서 다른 키 삭제 | q=a+%7E로 표기는 달라졌지만 읽은 값은 a ~ |
| 함수에 page=0·101·1.5·문자열 ‘2’ | 예제 계약 오류로 거절 |
브라우저 주소창 이동, History API, 실제 폼 제출, 서버 프레임워크·프록시·검색 API·서명 검증·캐시는 시험하지 않았습니다. Node의 왕복 성공을 서버 파서나 대상 브라우저의 성공으로 확대하지 않습니다. 본문 코드는 표시용이며 사이트에서 검색 서비스를 실행하지 않습니다.
실제 서비스에 적용할 때 확인할 순서
- 대상 브라우저에서 합성 검색어 C++, 공백, 한글, %2B 원문과 태그 두 개를 각각 넣습니다. 생성 문자열과 다시 읽은 값·개수를 비교합니다.
- 실제 요청에서 보내진 쿼리와 서버 파서 결과를 대조합니다. 서버가 중복 이름을 배열·첫 값·마지막 값 중 무엇으로 해석하는지 확인하고 모호한 단일 키는 거절하도록 계약을 맞춥니다.
- 검색·페이지 이동을 되돌린 뒤 조건이 복원되는지 확인합니다. 이 글은 주소 기록을 바꾸는 코드를 제공하지 않으므로 앱의 라우터 동작은 별도 시험합니다.
- 이미 서명되었거나 바이트 단위 비교가 필요한 URL은 이 함수로 다시 만들지 않습니다. 같은 의미여도 순서·공백 표기가 바뀌면 기존 서명·캐시 키 계약과 달라질 수 있으므로 해당 서비스의 공식 서명 규칙을 따릅니다.
앞 단계 값이 이미 달라졌다면 이후에 +나 %를 일괄 치환하지 말고 그 최초 경계의 입력 계약을 고칩니다. 서버 측 허용 값과 권한 검증도 유지합니다.
공식 원문과 확인일
2026년 11월 2일 아래 문서를 직접 열어 생성자 형식, +·공백 해석, 다중 키와 직렬화 규칙을 대조했습니다. 예제의 입력 제한과 검사 결과는 이 글에서 별도로 정한 범위입니다.