Чарльз Проксі

Charles Proxy полегшує налагодження HTTP-запитів, діючи як проксі-сервер "людина посередині", перехоплюючи та дозволяючи перевіряти й модифікувати весь мережевий трафік між клієнтською програмою та цільовими серверами.

Charles Proxy функціонує як локальний HTTP-проксі-сервер, що дозволяє розробникам та інженерам з контролю якості спостерігати, перехоплювати та маніпулювати мережевою комунікацією. Ця можливість є критично важливою для розуміння взаємодії клієнт-сервер, діагностики проблем інтеграції, тестування граничних випадків та перевірки поведінки API, особливо при роботі з сервісами, що взаємодіють з вищестоящим проксі-сервером, або їх розробці.

Налаштування Charles Proxy

Встановлення та перший запуск

Завантажте та встановіть Charles Proxy з його офіційного веб-сайту. При першому запуску Charles зазвичай намагається налаштувати себе як системний проксі-сервер. Прийміть цей запит, щоб дозволити Charles перехоплювати трафік від програм, які дотримуються системних налаштувань проксі.

Налаштування системних параметрів проксі

Коли Charles працює, він автоматично встановлює системні налаштування HTTP/HTTPS проксі на 127.0.0.1 (localhost) на порті 8888 (за замовчуванням). Більшість програм, включаючи веб-браузери, дотримуються цих налаштувань.

Щоб перевірити або налаштувати вручну:
* macOS: Системні налаштування > Мережа > Wi-Fi/Ethernet > Деталі > Проксі. Переконайтеся, що "Веб-проксі (HTTP)" та "Безпечний веб-проксі (HTTPS)" увімкнено та вказують на 127.0.0.1:8888.
* Windows: Налаштування > Мережа та Інтернет > Проксі > Налаштування проксі вручну. Переконайтеся, що "Використовувати проксі-сервер" увімкнено з 127.0.0.0.1 та портом 8888.
* Linux (GNOME): Налаштування > Мережа > Мережевий проксі. Встановіть Метод на "Вручну" та налаштуйте HTTP/HTTPS проксі на 127.0.0.1:8888.

Налаштування клієнтських програм

Деякі програми, зокрема інструменти командного рядка або певні SDK, можуть не дотримуватися загальносистемних налаштувань проксі. У таких випадках налаштуйте програму безпосередньо.

Приклад: curl з проксі

curl -x http://127.0.0.1:8888 https://api.example.com/data

Приклад: Node.js axios з проксі

const axios = require('axios');

axios.get('https://api.example.com/data', {
  proxy: {
    host: '127.0.0.1',
    port: 8888
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

SSL-проксіювання для HTTPS-трафіку

Щоб перевірити HTTPS-трафік, Charles Proxy повинен виконувати SSL (або TLS) проксіювання. Це передбачає, що Charles генерує та підписує сертифікати для цільових доменів, представляє їх клієнту, а потім встановлює власне безпечне з'єднання з реальним сервером.

Встановлення кореневого сертифіката Charles

Клієнтська програма повинна довіряти кореневому сертифікату Charles, щоб SSL-проксіювання працювало без попереджень безпеки.

• Настільні браузери/Система:
  • Перейдіть до Help > SSL Proxying > Install Charles Root Certificate. Дотримуйтесь підказок операційної системи, щоб встановити його в системне сховище довірених кореневих сертифікатів.
• Мобільні пристрої:
  • Налаштуйте мобільний пристрій на використання Charles як HTTP-проксі (наприклад, your_mac_ip:8888).
  • На пристрої перейдіть за адресою chls.pro/ssl та дотримуйтесь інструкцій для завантаження та встановлення сертифіката.

Увімкнення SSL-проксіювання для конкретних хостів

Після встановлення кореневого сертифіката увімкніть SSL-проксіювання для конкретних хостів, які ви бажаєте перевірити.

1. Перейдіть до Proxy > SSL Proxying Settings....
2. Натисніть "Add".
3. Введіть Host (наприклад, api.example.com, *.example.com для шаблону, або * для всіх хостів) та Port (зазвичай 443 для HTTPS, або * для всіх портів).
4. Натисніть "OK", а потім ще раз "OK".

Трафік до вказаних хостів тепер буде розшифрований та видимий у Charles.

Ключові функції налагодження

Моніторинг та фільтрація трафіку

Представлення "Structure" (Структура) та "Sequence" (Послідовність) відображають перехоплені запити.
* Sequence View (Вигляд послідовності): Показує запити в хронологічному порядку.
* Structure View (Вигляд структури): Організовує запити за хостом та шляхом.

Щоб зосередитися на відповідному трафіку:
* Filter Field (Поле фільтра): Використовуйте поле фільтра у верхній частині вікна Charles для пошуку за URL, хостами або вмістом.
* Focus Tool (Інструмент фокусування): Клацніть правою кнопкою миші на запиті та виберіть "Focus", щоб приховати всі інші хости з поточного вигляду.
* Record Button (Кнопка запису): Перемикайте кнопку запису (червоне коло), щоб почати/зупинити захоплення трафіку.

Точки зупинки (Breakpoints)

Точки зупинки дозволяють призупиняти та модифікувати запити перед їх надсиланням на сервер або відповіді перед їх надсиланням клієнту.

1. Перейдіть до Proxy > Breakpoints Settings....
2. Натисніть "Add" для запитів або відповідей.
3. Вкажіть Host та Path (наприклад, /login).
4. Коли запит/відповідь співпаде, Charles призупиниться, і з'явиться вкладка "Breakpoints".
5. Модифікуйте заголовки, параметри запиту або тіло.
6. Натисніть "Execute", щоб надіслати модифікований запит/відповідь.

Інструмент перезапису (Rewrite Tool)

Інструмент Rewrite забезпечує автоматичні, постійні модифікації запитів та відповідей. Це корисно для симуляції специфічної поведінки сервера або клієнтських умов без ручного втручання.

1. Перейдіть до Tools > Rewrite....
2. Увімкніть Rewrite та додайте новий "Set" (Набір).
3. Додайте "Locations" (URL-адреси, до яких застосовуються правила) за допомогою Host та Path.
4. Додайте "Rules" (Правила) в межах набору:
   • Add Header/Remove Header (Додати заголовок/Видалити заголовок): Модифікувати HTTP-заголовки.
   • Change Query Parameter (Змінити параметр запиту): Модифікувати параметри запиту URL.
   • Body Replace (Заміна тіла): Знайти та замінити текст у тілі запиту/відповіді.
   • URL Replace (Заміна URL): Модифікувати частини URL запиту.

Приклад: Модифікація тіла відповіді API
Правило Rewrite може замінити {"status": "active"} на {"status": "maintenance"} у JSON-відповіді, щоб перевірити, як клієнт обробляє різні стани.

Map Local / Map Remote

Ці інструменти перенаправляють запити до різних джерел.

• Map Local (Мапування на локальний файл): Обслуговує локальний файл замість віддаленої відповіді.

  1. Перейдіть до Tools > Map Local....
  2. Увімкніть Map Local та додайте новий запис.
  3. Вкажіть Host та Path віддаленого URL.
  4. Виберіть локальний шлях до File (файлу), який потрібно обслуговувати.
     Це корисно для швидкого тестування змін інтерфейсу користувача або симуляції специфічних відповідей API без модифікації бекенду.

• Map Remote (Мапування на віддалений ресурс): Перенаправляє запит для одного URL на зовсім інший URL.

  1. Перейдіть до Tools > Map Remote....
  2. Увімкніть Map Remote та додайте новий запис.
  3. Вкажіть Host та Path оригінального запиту.
  4. Вкажіть новий Host та Path для перенаправленого запиту.
     Корисно для перенаправлення викликів API на проміжне середовище (staging environment) або локальний сервер розробки.

Регулювання швидкості (Throttling)

Регулювання швидкості імітує повільні мережеві умови, допомагаючи виявити вузькі місця продуктивності або проблеми інтерфейсу користувача, пов'язані з повільним завантаженням даних.

1. Перейдіть до Proxy > Throttle Settings....
2. Увімкніть "Enable Throttling".
3. Налаштуйте параметри Bandwidth (Пропускна здатність), Utilisation (Використання) та Latency (Затримка).
4. За бажанням виберіть "Only for selected hosts" (Тільки для вибраних хостів) та додайте конкретні хости для регулювання.

Повтор (Repeat) / Розширений повтор (Advanced Repeat)

Ці функції дозволяють повторно надсилати запити.

• Repeat (Повтор): Клацніть правою кнопкою миші на запиті та виберіть "Repeat", щоб негайно надіслати його знову.
• Advanced Repeat (Розширений повтор): Клацніть правою кнопкою миші на запиті та виберіть "Advanced Repeat", щоб надіслати його кілька разів з налаштовуваною паралельністю та кількістю ітерацій. Це корисно для тестування навантаження або перевірки умов гонки.

Налагодження взаємодії з вищестоящим проксі

Коли ваша клієнтська програма налаштована на використання Charles, а сам Charles налаштований на використання вищестоящого проксі (наприклад, корпоративного проксі), Charles діє як посередник.

Щоб налаштувати Charles на використання вищестоящого проксі:
1. Перейдіть до Proxy > External Proxy Settings....
2. Увімкніть "Use external proxy".
3. Введіть Host, Port та будь-які необхідні Username/Password для вашого вищестоящого проксі.
4. Увімкніть "SOCKS proxy", якщо ваш вищестоящий проксі є SOCKS-проксі.

У цій конфігурації Charles перехоплює трафік від вашого клієнта, а потім пересилає його до вищестоящого проксі. Це дозволяє вам перевіряти трафік до того, як він досягне вищестоящого проксі, що є вирішальним для діагностики проблем, коли вищестоящий проксі може модифікувати запити або блокувати певні кінцеві точки.

Поширені проблеми та їх усунення

| Проблема | Рішення

CHARLES PROXY: НАЛАГОДЖЕННЯ HTTP-ЗАПИТІВ ЧЕРЕЗ ПРОКСІ

Charles Proxy налагоджує HTTP-запити, діючи як проксі-сервер "людина посередині", перехоплюючи весь мережевий трафік між клієнтською програмою та цільовими серверами, що дозволяє детально перевіряти та модифікувати його.

Огляд

Charles Proxy — це HTTP-проксі (HTTP/HTTPS/SOCKS) та HTTP-монітор, який працює на вашій локальній машині. Він дозволяє переглядати весь HTTP та HTTPS трафік між вашою машиною та Інтернетом. При налагодженні сервісів, що взаємодіють з вищестоящим проксі-сервером, Charles можна налаштувати так, щоб він знаходився між клієнтом та вищестоящим проксі, забезпечуючи видимість точних запитів, що надсилаються та отримуються вашою програмою.

Початкове налаштування

Встановлення

Завантажте та встановіть Charles Proxy з офіційного веб-сайту (charlesproxy.com). Charles підтримує macOS, Windows та Linux.

Налаштування системного проксі

При запуску Charles зазвичай пропонує налаштувати себе як системний проксі. Прийняття цього дозволяє Charles автоматично перехоплювати трафік від програм, налаштованих на використання системних параметрів проксі (наприклад, більшість веб-браузерів, Java-додатків, .NET-додатків).

Щоб вручну перевірити або налаштувати:
* Адреса проксі HTTP/HTTPS за замовчуванням: 127.0.0.1
* Порт проксі HTTP/HTTPS за замовчуванням: 8888

Для середовищ, де Charles потрібно підключитися до зовнішнього (вищестоящого) проксі:
1. Перейдіть до Proxy > External Proxy Settings....
2. Поставте прапорець "Use external proxy".
3. Введіть Host та Port вищестоящого проксі.
4. Надайте Username та Password, якщо це вимагається вищестоящим проксі.
5. Поставте прапорець "SOCKS proxy", якщо вищестоящий проксі є SOCKS-проксі.

Ця конфігурація гарантує, що Charles перехоплює трафік від вашого клієнта, а потім направляє його через вказаний зовнішній проксі, дозволяючи вам перевіряти, що надсилається та отримується від зовнішнього проксі.

SSL-проксіювання для HTTPS-трафіку

HTTP Secure (HTTPS) трафік зашифрований, що перешкоджає прямій перевірці. Charles використовує SSL-проксіювання (атака "людина посередині") для розшифровки та перевірки HTTPS-трафіку.

Встановлення кореневого сертифіката Charles

Щоб виконати SSL-проксіювання, Charles генерує динамічні SSL-сертифікати для кожного HTTPS-домену. Ваша клієнтська програма повинна довіряти кореневому сертифікату Charles, щоб уникнути помилок SSL.

• Настільні ОС (macOS/Windows/Linux):
  1. Перейдіть до Help > SSL Proxying > Install Charles Root Certificate.
  2. Дотримуйтесь підказок операційної системи, щоб встановити сертифікат у сховище довірених кореневих сертифікатів.
• Мобільні пристрої (iOS/Android):
  1. Налаштуйте параметри Wi-Fi мобільного пристрою для використання Charles як HTTP-проксі (IP-адреса Charles та порт 8888).
  2. На мобільному пристрої відкрийте браузер і перейдіть за адресою chls.pro/ssl.
  3. Дотримуйтесь інструкцій для завантаження та встановлення кореневого сертифіката Charles як довіреного облікового запису.

Увімкнення SSL-проксіювання для конкретних хостів

Після встановлення кореневого сертифіката вкажіть, які HTTPS-хости Charles повинен розшифровувати.
1. Перейдіть до Proxy > SSL Proxying Settings....
2. Натисніть "Add".
3. Введіть Host (наприклад, api.yourdomain.com, *.yourdomain.com або * для всіх хостів) та Port (зазвичай 443 або * для всіх портів).
4. Натисніть "OK".

Основні функції налагодження

Захоплення та фільтрація трафіку

Charles відображає захоплений трафік у двох основних виглядах:
* Sequence (Послідовність): Хронологічний список запитів.
* Structure (Структура): Ієрархічний вигляд, згрупований за хостом та шляхом до папки.

Щоб знайти конкретні запити:
* Filter Field (Поле фільтра): Використовуйте панель фільтра у верхній частині для пошуку за хостом, шляхом URL або вмістом.
* Focus Tool (Інструмент фокусування): Клацніть правою кнопкою миші на запиті та виберіть "Focus", щоб приховати всі інші хости з поточного вигляду.
* Record Button (Кнопка запису): Перемикайте піктограму червоного кола, щоб почати/зупинити захоплення трафіку.

Точки зупинки (Breakpoints)

Точки зупинки дозволяють вручну перехоплювати та модифікувати запити перед їх надсиланням або відповіді перед їх досягненням клієнта.

1. Перейдіть до Proxy > Breakpoints Settings....
2. Натисніть "Add" для точок зупинки "Request" або "Response".
3. Вкажіть шаблони Host та Path для цільового URL.
4. Коли відбувається відповідний запит/відповідь, Charles призупиняється, відображаючи вкладку "Breakpoints".
5. Модифікуйте Headers (Заголовки), Query Parameters (Параметри запиту) або вміст Body (Тіла).
6. Натисніть "Execute", щоб продовжити модифіковану транзакцію.

Інструмент перезапису (Rewrite Tool)

Інструмент Rewrite автоматизує модифікації запитів та відповідей на основі попередньо визначених правил. Це корисно для послідовних сценаріїв тестування без ручного втручання.

1. Перейдіть до Tools > Rewrite....
2. Увімкніть Rewrite та додайте новий "Set" (Набір).
3. Визначте "Locations" (Місця, де застосовуються правила) за допомогою Host та Path.
4. Додайте "Rules" (Правила) в межах набору:
   • Type (Тип): Add Header, Remove Header, Change Query Parameter, Host, Path, URL, Body.
   • Action (Дія): Вкажіть Value (Значення) або Regex (Регулярний вираз) для модифікації.

Приклад: Симуляція зміни версії API
Правило Rewrite може змінити заголовок Accept з application/json;v=1 на application/json;v=2 для всіх запитів до конкретної кінцевої точки API.

Map Local / Map Remote

Ці функції перенаправляють запити до альтернативних ресурсів.

• Map Local (Мапування на локальний файл): Обслуговує локальний файл замість відповіді від віддаленого сервера.

  1. Перейдіть до Tools > Map Local....
  2. Увімкніть Map Local та додайте новий запис.
  3. Вкажіть Host та Path віддаленого URL, який потрібно мапувати.
  4. Виберіть Local Path (Локальний шлях) до файлу, який Charles повинен обслуговувати.
     Це корисно для фронтенд-розробки, щоб тестувати зміни інтерфейсу користувача з конкретними макетними даними без модифікації бекенду.

• Map Remote (Мапування на віддалений ресурс): Перенаправляє запит з одного URL на зовсім інший URL.

  1. Перейдіть до Tools > Map Remote....
  2. Увімкніть Map Remote та додайте новий запис.
  3. Вкажіть Host та Path оригінального запиту.
  4. Вкажіть Host та Path нового цільового URL.
     Це корисно для перенаправлення викликів API з продакшн-середовища на проміжне середовище (staging environment) або локальний сервер розробки.

Регулювання швидкості (Throttling)

Регулювання швидкості імітує різні мережеві умови (наприклад, dial-up, 3G, власні швидкості) для тестування продуктивності та чутливості програми за умов неоптимального мережевого з'єднання.

1. Перейдіть до Proxy > Throttle Settings....
2. Поставте прапорець "Enable Throttling".
3. Виберіть Preset (Попереднє налаштування) або налаштуйте Bandwidth (Пропускна здатність), Utilisation (Використання) та Latency (Затримка) вручну.
4. За бажанням, поставте прапорець "Only for selected hosts" (Тільки для вибраних хостів) та додайте конкретні хости для регулювання.

Повтор (Repeat) / Розширений повтор (Advanced Repeat)

Ці функції дозволяють повторно надсилати запити.
* Repeat (Повтор): Клацніть правою кнопкою миші на запиті в сесії Charles та виберіть "Repeat", щоб надіслати його ще раз.
* Advanced Repeat (Розширений повтор): Клацніть правою кнопкою миші на запиті та виберіть "Advanced Repeat", щоб налаштувати кілька повторень, паралельність та затримки, що корисно для базового тестування навантаження або перевірки ідемпотентності.

Усунення поширених сценаріїв

| Проблема | Рішення