Наперед 1.0: Готовість до виробництва УмаміM SK1NET
Введение
Коли я вперше Аналітика Умамі в мою блогову платформу, Я швидко потрапив у розчаровуючу реальність : UmamiM SK2s API документація є МSK3 дозволять МСК4 бути доброчинним і називати його М С К 5 мінімальний М S К 6 Сообщення про помилки є криптичними в найкращому випадку M С К 7 не ’ М С С К 8 ’ є в найгіршому випадку ’ M С K 9 ’ Параметри змінюються між версіями без попередження M S К 10 ’ І навіть не змусять мене почати на М С К 12 ’ бп боп ‘ М С K 13 ’ ботов реагування на виявлення роботів ’ Б С К 14 ’
Тож я створив Umami.NET - не просто як простий HTTP упаковник ,, а як продуктивна МSK2 готова клиентська бібліотека, яка компенсує всі недоліки Umami M SK3 . Як і Я MSC5 я працювала над МСК6 релізом М СК7 Я М סК8 зосередилася на трьох критичних галузях M СК9
- Комплексне перевірки з допомогою корисних повідомлень про помилки
- Robust testing infrastructure
- Милозливе подолання помилок для реальних сценаріїв -world
Дозвольте мені показати вам, що робить цю бібліотеку продуктивною.
Проблема: UmamiM SK1s Documentation Gap
Ось з чим ви зіткнулися під час роботи з API Umami
- Нічого не підтверджує - Посилати неправильне GUID? Беззвучний похибкаM SK2
- Криптичні реакції - Bot detectedM SK1 Ви отримуєте
"beep boop"МSK0 Це ' це . - Перехилення змін - Параметри переименовані між версіями
pathпротиurl,hostnameпротиhost) - Заплутаність тайм-тамп - Унікс-мілісекунди ? SekundіM SK2 Щиро дякую, що ви зрозуміли це.
- Відповіді JWT - Іноді повні вантажі , іноді просто ID для відвідувачів МSK2 Немає документів, які пояснюють, коли чи чому
Це добре для швидкого прототипу , але для виробництва? Вам потрібно щось кращеM SK2
Клаузи охорони: Зазнають невдачі у контексті
Найгірші помилки - ті, що беззвучно зазнають невдачі.
Проверка конфігурації
public static void ValidateSettings(UmamiClientSettings settings)
{
// Guard: UmamiPath is required
if (string.IsNullOrEmpty(settings.UmamiPath))
throw new ArgumentNullException(settings.UmamiPath,
"UmamiUrl is required");
// Guard: UmamiPath must be valid URI
if (!Uri.TryCreate(settings.UmamiPath, UriKind.Absolute, out _))
throw new FormatException(
"UmamiUrl must be a valid Uri");
// Guard: WebsiteId is required
if (string.IsNullOrEmpty(settings.WebsiteId))
throw new ArgumentNullException(settings.WebsiteId,
"WebsiteId is required");
// Guard: WebsiteId must be valid GUID
if (!Guid.TryParseExact(settings.WebsiteId, "D", out _))
throw new FormatException(
"WebSiteId must be a valid Guid");
}
Це відбувається на початку вашого Program.cs. Якщо ваша конфігурація неправильнаM SK1 ви одразу ж знаєте - не тоді, коли перший аналізовий випадок намагається надіслати
Вимагати перевірки з допоміжними підказками
Але справжня магія полягає в допомічникі строків запиту. Подивіться на ці повідомлення
public static string ToQueryString(this object obj)
{
if (obj == null)
{
throw new ArgumentNullException(nameof(obj),
"Cannot convert null object to query string. " +
"Suggestion: Ensure you create and populate a request object " +
"before calling ToQueryString().");
}
foreach (var property in objectType.GetProperties())
{
if (attribute.IsRequired)
{
if (propertyValue == null)
{
throw new ArgumentException(
$"Required parameter '{propertyName}' " +
$"(property '{property.Name}') cannot be null. " +
$"Suggestion: Set the {property.Name} property " +
$"on your {objectType.Name} object...",
property.Name);
}
// For strings, check for empty/whitespace
if (propertyValue is string strValue &&
string.IsNullOrWhiteSpace(strValue))
{
throw new ArgumentException(
$"Required parameter '{propertyName}' " +
$"cannot be empty or whitespace. " +
$"Suggestion: Set {property.Name} to a valid non-empty value.",
property.Name);
}
}
}
}
Зверніть увагу на Suggestion: prefix? Кожне повідомлення про помилку говорить вам що пішло не так і як це виправити. Це документація, яку мав би надати Умамі
Проверка діапазону даних
При створенні аналітиких запитів, діапазони дати можуть бути складнимиM SK1 Бібліотека вловлює ці помилки для вас
public DateTime StartAtDate
{
get => _startAtDate;
set
{
if (_endAtDate != default && value > _endAtDate)
{
throw new ArgumentException(
$"StartAtDate ({value:O}) must be before EndAtDate ({_endAtDate:O}). " +
"Suggestion: Set StartAtDate to an earlier date or adjust EndAtDate.",
nameof(StartAtDate));
}
_startAtDate = value;
}
}
public virtual void Validate()
{
if (StartAtDate == default)
{
throw new InvalidOperationException(
"StartAtDate is required. " +
"Suggestion: Set StartAtDate to a valid date " +
"(e.g., DateTime.UtcNow.AddDays(-7) for last 7 days).");
}
}
Обладнання помилками Умамі
Проблема "Beep BoopM SK1
Умі's розпізнавання робота повертає просту текстову відповідь "beep boop". Не JSONM SK1 Неправильний код статусу. ПростоMSC3 гейп-бопМSK4
Ось як обробляє його Umami, ., NET
public async Task<UmamiDataResponse> DecodeResponse(HttpResponseMessage response)
{
var responseString = await response.Content.ReadAsStringAsync();
// Handle bot detection
if (responseString.Contains("beep") && responseString.Contains("boop"))
{
logger.LogWarning("Bot detected - data not stored in Umami");
return new UmamiDataResponse(ResponseStatus.BotDetected);
}
// Handle JWT response
try
{
var jwtPayload = DecodeJwt(responseString);
return new UmamiDataResponse(ResponseStatus.Success, jwtPayload);
}
catch (Exception e)
{
logger.LogError(e, "Failed to decode response");
return new UmamiDataResponse(ResponseStatus.Failed);
}
}
Ваш код отримує чистий енум:
public enum ResponseStatus
{
Failed,
BotDetected,
Success
}
Немає більше дивних відповідей для аналізу. - просто перевіряйте статус
Зміни на ім 'я параметрів
Умамі переименував параметри між версіями API. Чи вони це документували? ? Звичайно, ні МSK2 Бібліотека обробляє їх обидва:
// Support both old and new parameter names
request.Path = queryParams["path"] ?? queryParams["url"];
request.Hostname = queryParams["hostname"] ?? queryParams["host"];
Перетворення на тайм-тамп
Умамі використовує Unix мілісекунд для тайм-тампів.
public static long ToMilliseconds(this DateTime dateTime)
{
var dateTimeOffset = new DateTimeOffset(dateTime.ToUniversalTime());
return dateTimeOffset.ToUnixTimeMilliseconds();
}
Тепер ви можете працювати з нормою DateTime об 'єкти і дозволити бібліотеці виконувати конвертацію.
Обробка фону з каналами
Аналітики ніколи не мають блокувати вашу програму. UmamiM SK1NET включає в себе відправника, який використовує System.Threading.Channels:
public class UmamiBackgroundSender : IHostedService
{
private readonly Channel<UmamiPayload> _channel;
private readonly UmamiClient _client;
public async Task Track(string eventName,
string? url = null,
UmamiEventData? data = null)
{
var payload = new UmamiPayload
{
Website = _settings.WebsiteId,
Name = eventName,
Url = url ?? string.Empty,
Data = data
};
// Non-blocking write to channel
await _channel.Writer.WriteAsync(payload);
}
private async Task ProcessQueue(CancellationToken stoppingToken)
{
await foreach (var payload in _channel.Reader.ReadAllAsync(stoppingToken))
{
try
{
await _client.Send(payload);
}
catch (Exception ex)
{
_logger.LogError(ex, "Failed to send event to Umami");
}
}
}
}
Мери стоять в черзі в пам 'яті і обробляються асинхронно. Ваші веб-запити повертаються миттєвоM SK1 аналіз відбувається у фоні.
Знову спробувати політику з Поллі
Спустошення мережі трапляється. Бібліотека використовує Polly для стійких HTTP дзвінків:
public static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy()
{
var delay = Backoff.DecorrelatedJitterBackoffV2(
TimeSpan.FromSeconds(1),
retryCount: 3);
return HttpPolicyExtensions
.HandleTransientHttpError()
.OrResult(msg => msg.StatusCode == HttpStatusCode.ServiceUnavailable)
.WaitAndRetryAsync(delay);
}
Перехідні невдачі та помилки 503 призводять до автоматичних повторів з експоненційним відхиленням . Ваша аналітика гнучка до тимчасових проблем з мережею МSK2
Authentication with Auto-Retry
Коли вибираєте аналізні дані ( не просто надсилаєте подіїM SK1 вам потрібна аутентифікація . Бібліотека автоматизує виведення токенів
public async Task<UmamiResult<StatsResponseModel>> GetStats(StatsRequest statsRequest)
{
var response = await _httpClient.GetAsync(url);
// Token expired? Re-authenticate and retry
if (response.StatusCode == HttpStatusCode.Unauthorized)
{
await _authService.Login();
return await GetStats(statsRequest); // Recursive retry
}
// Parse and return
var content = await response.Content.ReadFromJsonAsync<StatsResponseModel>();
return new UmamiResult<StatsResponseModel>(
response.StatusCode,
response.ReasonPhrase ?? string.Empty,
content);
}
Вам ніколи не потрібно думати про управління токенами.
Тестування інфраструктури
Produkція- готовий код потребує комплексних тестів . ТутM SK2 це те, що я збудував
FakeLogger для перевірки журналу
Використовуючи Microsoft's FakeLogger пакет, тести можуть перевірити логінг
[Fact]
public async Task Login_Success_LogsMessage()
{
// Arrange
var fakeLogger = new FakeLogger<AuthService>();
var authService = new AuthService(httpClient, settings, fakeLogger);
// Act
await authService.Login();
// Assert
var logs = fakeLogger.Collector.GetSnapshot();
Assert.Contains("Login successful", logs.Select(x => x.Message));
}
Керівники HTTP Custom Mock
Випробовування асинхових операцій складно. TaskCompletionSource:
[Fact]
public async Task BackgroundSender_ProcessesEventAsynchronously()
{
var tcs = new TaskCompletionSource<bool>();
var handler = EchoMockHandler.Create(async (message, token) =>
{
try
{
// Assert the request was sent correctly
var payload = await message.Content.ReadFromJsonAsync<UmamiPayload>();
Assert.Equal("test-event", payload.Name);
tcs.SetResult(true); // Signal test completion
return new HttpResponseMessage(HttpStatusCode.OK);
}
catch (Exception e)
{
tcs.SetException(e);
return new HttpResponseMessage(HttpStatusCode.InternalServerError);
}
});
// Track event
await backgroundSender.Track("test-event");
// Wait for background processing with timeout
var completedTask = await Task.WhenAny(tcs.Task, Task.Delay(1000));
if (completedTask != tcs.Task)
throw new TimeoutException("Event was not processed within timeout");
await tcs.Task; // Throw if assertions failed
}
Ця модель гарантує:
- Взагалі-то оброблені події
- Обробка закінчується в зручний час
- Вказівки у регулювальнику макетів надлежало повідомляти
Комплексне тестування
Тестовий пакет obejmuje:
- ✅ Веріалізація конфігурації (неправильні GUIDsM SK2 бракуючих URLsМSK3
- ✅ Переслідування подій з і без даних
- ✅ Переслідування сторінки
- ✅ Identyfikacja користувача
- ✅ Рухування при виявленні Bot
- ✅ Кодування реакції JWT
- ✅ Обробка фону з перервами часу
- ✅ Validaція діапазону даних
- ✅ генерування строків запиту
- ✅ Аuthentication and token refresh
- ✅ Перетягування даних вимірів та сторінок
Реальний- Світове використання
Ось як просто це використовувати в ASP
Установка в програмі.cs
builder.Services.SetupUmamiClient(builder.Configuration);
Що's itM SK1 Бібліотека читає ваші appsettings.json:
{
"Analytics": {
"UmamiPath": "https://analytics.yoursite.com",
"WebsiteId": "your-website-guid"
}
}
Відповіді про події
public class HomeController : Controller
{
private readonly UmamiBackgroundSender _umami;
public HomeController(UmamiBackgroundSender umami)
{
_umami = umami;
}
public IActionResult Index()
{
// Non-blocking event tracking
await _umami.TrackPageView("/", "Home Page");
return View();
}
[HttpPost]
public async Task<IActionResult> Subscribe(string email)
{
// Track with custom data
await _umami.Track("newsletter-signup",
data: new UmamiEventData
{
{ "source", "homepage" },
{ "email_domain", email.Split('@')[1] }
});
return RedirectToAction("ThankYou");
}
}
Перейти до даних аналітики
public class AnalyticsDashboardController : Controller
{
private readonly IUmamiDataService _umamiData;
public async Task<IActionResult> Stats()
{
var request = new StatsRequest
{
StartAtDate = DateTime.UtcNow.AddDays(-30),
EndAtDate = DateTime.UtcNow
};
var result = await _umamiData.GetStats(request);
if (result.Status == HttpStatusCode.OK)
{
var stats = result.Data;
// stats.Visitors, stats.PageViews, stats.BounceRate, etc.
return View(stats);
}
return View("Error");
}
}
Що Next for 1.0?
Бібліотека є функцією-повне та боєздатнаМSK1тестована в розробці на цьому самому блогіМСК2 Перед випуском MСК3 МСК4 ЯМ СК5 я зосереджуся наМSК6
- 📝 Комплексна документація API
- 🎯 Публикація пакетів NuGet
- 📊 Benchmarks Performance
- 🔧 Додаткові методи зручності для загальних аналізних запитів
Завершення
Побудувати готову бібліотеку для виробництва - це не просто обгортання API, а створення такого досвіду. краще ніж безпосередньо використовувати API. NET compensates for Umami's documentation gaps with
- Виновлення, яке пояснює, що пішло не так і як його виправити
- Гарний підхід до химерних API поведінки
- Комплексне тестування, яке доводить, що це працює
- Обробка фону, яка не блокує ваші додатки
- Витримувальне використання помилок з автоматичними повторами
Якщо ви' використовуєте аналізи Умамі в .NET програмі(МSK2), я(M SK3) хочу, щоб ви спробували Umami.NET. Це МSK1 відкритий вихідний код МSK2 серйозно тестований , і розроблений для того, щоб зробити ваше життя легшим
У мене є питання чи підказки? Відкрийте проблему на GitHub або зверніть увагу на її коментарі