Вступ

Стандартизація відповідей API є критично важливою для побудови масштабованих та зручних для обслуговування систем. У цій статті ми розглянемо впровадження загального класу ApiResponse на C# для Azure Functions та відповідну обробку в TypeScript. Також ми обговоримо проблеми відсутності стандартизованих відповідей, переваги збирання помилок та найкращі практики для реалізації.

Реалізація ApiResponse в C

Оновлений клас ApiResponse

Оновлена реалізація підтримує надійне оброблення помилок, відстеження за допомогою CorrelationId та зрозумілі для людини повідомлення про помилки.

public class ApiResponse : BaseApiResponse  
{  
 public T Result { get; set; }  
 public ApiResponse() { }  
 public ApiResponse(T result)  
 {  
 Result = result;  
 }  
}  

public abstract class BaseApiResponse  
{  
 public string CorrelationId { get; set; } = Guid.NewGuid().ToString();  
 public IReadOnlyList<ApiError> Errors { get; protected set; } = new List<ApiError>();  

 public void AddError(ApiError error)  
 {  
 ((List<ApiError>)Errors).Add(error);  
 }  
 public int ErrorCount => Errors.Count;  
 public bool IsSuccessful => !Errors.Any();  
}  

public class ApiError  
{  
 public string PropertyName { get; set; }  
 public string ErrorMessage { get; set; }  
 public string ErrorCode { get; set; }  
 public ApiError(string propertyName, string errorMessage, string errorCode = null)  
 {  
 PropertyName = propertyName;  
 ErrorMessage = errorMessage;  
 ErrorCode = errorCode;  
 }  
}

Приклад Azure Function

[FunctionName("GetData")]  
public static async Task<ApiResponse> GetData(  
 [HttpTrigger(AuthorizationLevel.Function, "get", Route = "data")] HttpRequest req,  
 ILogger log)  
{  
 log.LogInformation("Обробка запиту GetData.");  

 var data = new { Id = 1, Name = "Sample Data" };  

 var response = new ApiResponse<object>  
 {  
     Result = data  
 };  

 if (data == null)  
 {  
     response.AddError(new ApiError("Data", "No data found"));  
 }

 return response;  
}  

**Зрозумілі для людини помилки**: Помилки можуть прямо відображатися на полях у тілі запиту, покращуючи досвід користувача.

{ "errors": [{ "propertyName": "email", "errorMessage": "Email is invalid." }, { "propertyName": "password", "errorMessage": "Password must be at least 8 characters." }] }
```

1. Порушення бізнес-правил: Чітко повідомляйте про проблеми, як-от недостатні права доступу чи недійсні операції.

{ "errors": [{ "propertyName": "businessRule", "errorMessage": "Insufficient balance to complete the transaction." }] }

1. Покращене налагодження за допомогою Correlation ID: Відслідковуйте запити від початку до кінця через системи.
2. Масштабованість: Додавайте нові типи помилок без порушення роботи існуючих клієнтів.

Кращі практики реалізації

• Включайте Correlation ID: Передавайте його як заголовок або параметр запиту для відстеження запитів від початку до кінця.
• Розділяйте помилки валідації та бізнес-правил: Використовуйте PropertyName для помилок валідації та businessRule для порушень логіки.
• Логуйте помилки з Correlation ID: Це допомагає в налагодженні та аналітиці.
• Документуйте структуру помилок: Забезпечте, щоб клієнти розуміли, як обробляти відповіді.

Висновок

Використання стандартизованої структури ApiResponse з колекціями помилок та Correlation ID покращує узгодженість, підтримуваність і можливості налагодження. Хоча це додає невелике навантаження на дані, переваги значно перевищують недоліки, особливо для складних або розподілених систем. Дотримуючись найкращих практик, ви можете створювати API, які є надійними, масштабованими та легкими для інтеграції.

Часті питання

1. Чому використовувати ApiResponse замість сирих відповідей? ApiResponse забезпечує постійну структуру, що покращує підтримуваність і обробку помилок.
2. Як допомагає CorrelationId ? Це дозволяє відслідковувати та налагоджувати запити в розподілених системах.
3. Для чого використовується IsSuccessful ? Це дає швидкий спосіб перевірити, чи вдалася операція, незалежно від HTTP статусу.
4. Чи можу я додавати більше полів до ApiResponse? Так, ви можете розширити його такими полями, як ErrorCode або AdditionalData, за потреби.
5. Як обробляти зламані зміни в структурі відповіді? Використовуйте версіювання в API, щоб забезпечити зворотну сумісність для існуючих клієнтів.

Перекладено з: Using ApiResponse in Azure Functions and TypeScript: A Comprehensive Guide