backend-architecture

后端架构

当前边界

• src/Exceptionless.Web/Api/Endpoints/：Minimal API 路由注册、绑定、授权和响应元数据。
• Api/Messages/ 和 Api/Handlers/：mediator 请求及其应用行为。请遵循对应的端点系列。
• Api/Filters/、Api/Infrastructure/ 和 Api/Results/：共享验证、请求辅助工具和 HTTP 结果映射。
• Exceptionless.Core：领域模型、服务、存储库、计费和序列化。
• Exceptionless.Insulation：存储、缓存、邮件和其他基础设施的提供程序实现。
• Exceptionless.Job：后台处理。

端点示例请阅读 src/Exceptionless.Web/Api/Endpoints/OrganizationEndpoints.cs，并同时查看其消息和处理器。端点组使用 AuthorizationRoles 策略和 AutoValidationEndpointFilter；mediator 结果通过 ToHttpResult 和已配置的结果映射器进行映射。请保留端点的响应和授权契约，不要照搬通用示例重新实现。

仓库约定

将领域行为保留在 Core 中：Web 和 Job 使用 Core，而 Insulation 提供基础设施实现。不要将 HTTP 相关逻辑移入领域服务。

• 直接注入 AppOptions。非机密设置使用 appsettings.yml；环境变量覆盖使用 EX_ 前缀。
• 使用 Foundatio 抽象处理缓存、队列、消息总线、文件存储、分布式锁和弹性机制。Elasticsearch 操作请使用 foundatio-repositories。
• 队列条目在持久化处理成功后完成。区分可重试故障和无效输入。
• 在支持的情况下传递取消信号。使用结构化日志，并通过 ExceptionlessState 作用域记录组织和项目上下文。
• WebSocket 通知使用 MessageBusBroker 和 WebSocketConnectionManager，并由消息总线提供支持。
• 遵循根目录指南中的 OpenAPI 快照和兼容性要求。更改 JSON 行为时，请参阅序列化架构。

实现细节

• 优先使用构造函数注入和只读依赖字段。遵循 .editorconfig，异步方法使用 Async 后缀，并避免添加 region。
• 使用 ICacheClient、IQueue<T>、IMessageBus、IFileStorage、ILockProvider 和 IResiliencePolicyProvider，不要创建针对特定提供程序的平行抽象。
• 队列使用者通常继承 QueueJobBase<T>；计划任务使用 JobWithLockBase 等基类以及 [Job] 计划属性。修改任务时请保留锁、完成、放弃和取消行为。无效输入不应进入无休止的重试循环。
• 使用 DataAnnotations 和现有的 MiniValidation 集成来验证模型。保留端点绑定和验证错误，以及 mediator 到 HTTP 的结果映射；请检查 Api/Filters/AutoValidationEndpointFilter.cs、Api/Results/ApiResultMapper.cs 和端点测试，确认预期的状态码和 ProblemDetails 格式。
• 使用结构化消息模板，不要使用插值日志消息；使用 ExceptionlessState 提供共享上下文。切勿记录密码、API 密钥、完整令牌或敏感负载；请优先记录必要的标识符和安全摘要。