mirror of
https://github.com/Govor-team/Govor.git
synced 2026-11-16 20:56:03 +00:00
GITBOOK-14: Govor.API: документация по текущему коду и диагностика 03.10.2026
This commit is contained in:
committed by
gitbook-bot
parent
4603be9f71
commit
6c8abb23e3
@@ -5,160 +5,51 @@ description: >-
|
||||
messages. It supports various HTTP-like status cod
|
||||
---
|
||||
|
||||
# HubResult\<T>
|
||||
# Ответы, ошибки и сериализация
|
||||
|
||||
**Namespace**: `Govor.Contracts.Responses.SignalR`
|
||||
## HTTP
|
||||
|
||||
### <mark style="color:$info;">Properties</mark>
|
||||
ResultExtensions преобразует Result\<T, Error>: успешный T → 200 со значением; Unit → 204 без тела.
|
||||
|
||||
* **Status**: (`HubResultStatus`) Indicates the status of the hub operation, corresponding to HTTP-like status codes (e.g., Success, BadRequest).
|
||||
* **Result**: (`T?`) The data returned by the hub operation, if applicable. Can be null for error cases or when no data is returned.
|
||||
* **ErrorMessage**: (`string?`) A message describing the error, if the operation failed. Null for successful operations.
|
||||
| ErrorType | HTTP |
|
||||
| ------------------------------ | ---------------------------- |
|
||||
| Validation | 400 |
|
||||
| NotFound | 404 |
|
||||
| Conflict | 409 |
|
||||
| Unauthorized | 401 |
|
||||
| Forbidden | 403 |
|
||||
| Остальные, включая ServerError | 400 (текущий дефект mapping) |
|
||||
|
||||
### <mark style="color:$info;">Static Methods</mark>
|
||||
Сервисная ошибка:
|
||||
|
||||
#### Ok
|
||||
|
||||
**Description**: Creates a successful result with an optional data payload.\
|
||||
**Parameters**:
|
||||
|
||||
* `result`: (`T?`, optional) The data to include in the response (default: `null`).\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `Success` (200) and the provided `result`.\
|
||||
**Example**:
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.Ok("Operation completed");
|
||||
```json
|
||||
{"status":404,"title":"Not Found","detail":"<описание>","errorCode":"<код>"}
|
||||
```
|
||||
|
||||
#### Created
|
||||
errors добавляется при наличии. Автоматическая MVC-валидация, middleware авторизации и ручные BadRequest/StatusCode могут возвращать другую форму. Единого тела ошибки для всех маршрутов сейчас нет.
|
||||
|
||||
**Description**: Creates a result indicating a resource was created, with an optional data payload.\
|
||||
**Parameters**:
|
||||
В контроллерах встречается Forbid(ex.Message): строка трактуется как authentication scheme, а не тело ответа; результат может быть 500 вместо 403.
|
||||
|
||||
* `result`: (`T?`, optional) The data to include in the response (default: `null`).\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `Created` (201) and the provided `result`.\
|
||||
**Example**:
|
||||
## SignalR HubResult
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.Created("Resource created");
|
||||
```json
|
||||
{"status":200,"result":null,"errorMessage":null}
|
||||
```
|
||||
|
||||
#### NoContent
|
||||
status — число внутри ответа команды, не HTTP-статус соединения. Значения: 200 Success, 201 Created, 204 NoContent, 400 BadRequest, 401 Unauthorized, 404 NotFound, 409 Conflict, 422 UnprocessableEntity, 500 ServerError.
|
||||
|
||||
**Description**: Creates a result indicating the operation was successful but no data is returned.\
|
||||
**Parameters**: None\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `NoContent` (204) and `Result` set to `null`.\
|
||||
**Example**:
|
||||
Static factories: Ok(result), Created(result), NoContent(), BadRequest(message, details), NotFound(message, details), Unauthorized(message), Conflict(message), UnprocessableEntity(message), Error(message).
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.NoContent();
|
||||
```
|
||||
Каждый хаб сам преобразует бизнес-ошибки; наличие enum не гарантирует точный status для каждого Failure. HubExceptionFilter возвращает Task.FromResult(errorResult) вместо объекта результата из InvokeMethodAsync; исключения вне локальных catch требуют исправления и проверки сериализации.
|
||||
|
||||
#### BadRequest
|
||||
## JSON-контракт
|
||||
|
||||
**Description**: Creates a result indicating a client error due to invalid input.\
|
||||
**Parameters**:
|
||||
Стандартные ASP.NET настройки используют camelCase; enum передаются числами, Guid — строками, byte\[] — base64, даты — ISO 8601. StringEnumConverter явно не настроен.
|
||||
|
||||
* `message`: (`string`) The error message describing the issue.
|
||||
* `details`: (`T?`, optional) Additional details about the error (default: `null`).\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `BadRequest` (400), the provided `message`, and optional `details`.\
|
||||
**Example**:
|
||||
HTTP MessageResponse.id и SignalR UserMessageResponse.messageId отличаются. HTTP и SignalR вложения также имеют разные структуры. Клиент должен иметь явное преобразование; не подменяйте один DTO другим.
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.BadRequest("Invalid input provided");
|
||||
```
|
||||
***
|
||||
|
||||
#### NotFound
|
||||
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
|
||||
|
||||
**Description**: Creates a result indicating a requested resource was not found.\
|
||||
**Parameters**:
|
||||
|
||||
* `message`: (`string`) The error message describing the issue.
|
||||
* `details`: (`T?`, optional) Additional details about the error (default: `null`).\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `NotFound` (404), the provided `message`, and optional `details`.\
|
||||
**Example**:
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.NotFound("User not found");
|
||||
```
|
||||
|
||||
#### Unauthorized
|
||||
|
||||
**Description**: Creates a result indicating the client is not authorized to perform the operation.\
|
||||
**Parameters**:
|
||||
|
||||
* `message`: (`string`) The error message describing the issue.\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `Unauthorized` (401) and the provided `message`.\
|
||||
**Example**:
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.Unauthorized("Authentication required");
|
||||
```
|
||||
|
||||
#### Conflict
|
||||
|
||||
**Description**: Creates a result indicating a conflict, such as a duplicate resource.\
|
||||
**Parameters**:
|
||||
|
||||
* `message`: (`string`) The error message describing the issue.\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `Conflict` (409) and the provided `message`.\
|
||||
**Example**:
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.Conflict("Resource already exists");
|
||||
```
|
||||
|
||||
#### UnprocessableEntity
|
||||
|
||||
**Description**: Creates a result indicating the request could not be processed due to semantic errors.\
|
||||
**Parameters**:
|
||||
|
||||
* `message`: (`string`) The error message describing the issue.\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `UnprocessableEntity` (422) and the provided `message`.\
|
||||
**Example**:
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.UnprocessableEntity("Invalid data format");
|
||||
```
|
||||
|
||||
#### Error
|
||||
|
||||
**Description**: Creates a result indicating an internal server error.\
|
||||
**Parameters**:
|
||||
|
||||
* `message`: (`string`) The error message describing the issue.\
|
||||
**Returns**: A `HubResult<T>` with `Status` set to `ServerError` (500) and the provided `message`.\
|
||||
**Example**:
|
||||
|
||||
```csharp
|
||||
HubResult<string> result = HubResult<string>.Error("Unexpected server error");
|
||||
```
|
||||
|
||||
### <mark style="color:$info;">Enum: HubResultStatus</mark>
|
||||
|
||||
**Description**: Enumerates the possible status codes for a `HubResult<T>` response, aligning with HTTP status codes for consistency in SignalR hub operations.
|
||||
|
||||
**Values**:
|
||||
|
||||
* <mark style="color:$success;">**Success**</mark> (200): The operation was successful.
|
||||
* <mark style="color:$success;">**Created**</mark> (201): A resource was successfully created.
|
||||
* <mark style="color:$success;">**NoContent**</mark> (204): The operation was successful, but no content is returned.
|
||||
* <mark style="color:$danger;">**BadRequest**</mark> (400): The request was invalid or malformed.
|
||||
* <mark style="color:$danger;">**Unauthorized**</mark> (401): The client is not authorized to perform the operation.
|
||||
* <mark style="color:$danger;">**NotFound**</mark> (404): The requested resource was not found.
|
||||
* <mark style="color:$danger;">**Conflict**</mark> (409): The request conflicts with an existing resource.
|
||||
* <mark style="color:$danger;">**UnprocessableEntity**</mark> (422): The request could not be processed due to semantic errors.
|
||||
* <mark style="color:$warning;">**ServerError**</mark> (500): An unexpected server error occurred.
|
||||
|
||||
### Example Usage
|
||||
|
||||
```csharp
|
||||
// Successful operation with data
|
||||
var successResult = HubResult<UserDto>.Ok(new UserDto { Id = Guid.NewGuid(), Username = "example" });
|
||||
|
||||
// Error due to invalid input
|
||||
var errorResult = HubResult<UserDto>.BadRequest("Invalid username provided");
|
||||
|
||||
// Not found scenario
|
||||
var notFoundResult = HubResult<UserDto>.NotFound("User not found in database");
|
||||
```
|
||||
Источник: [Govor.API/Common/Extensions/ResultExtensions.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Common/Extensions/ResultExtensions.cs).
|
||||
|
||||
Reference in New Issue
Block a user