Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

RFC 9457 Problem Details for HttpApi errors

未关闭
  • 哪里不对？
#9,686 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

@effect-bot 已经在做这个了。

开始于 2026年10月21日。

  • #9706 来自 @effect-bot —— 未关闭

评估

难度
5/5
预计耗时
一周以上
新手友好度
20/100
Issue 类型
功能
描述清晰度
描述清楚
活跃度
停滞
技术栈
typescript
领域
backend-api-design

调研方向

Start with packages/effect/src/http-api/HttpApiError.ts and the existing HttpApi middleware, schema, OpenAPI, and client paths named in the proposal. Review linked pull request #9706 and issue #5367 before considering scope; the issue leaves package placement and decode disclosure open. Done means implementing the proposed Problem Details schema, typed errors, opt-in rendering, OpenAPI support, and client decoding while preserving the default empty-body behavior.

由索引模型根据 Issue 内容生成。

描述

docker-made-me-do-it enhancement

Problem

RFC 9457 (application/problem+json) is the standard JSON format for HTTP API errors. HttpApi doesn't support it, and by default its errors have no body:

  • The built-in errors (HttpApiError.BadRequest, NotFound, and so on) are sent as empty responses (packages/effect/src/http-api/HttpApiError.ts:23-56).
  • When a request fails to decode, the server answers with an empty 400 (HttpApiError.ts:507). The client gets no indication of which field was wrong or why.

You can build Problem Details yourself with HttpApiMiddleware.layerSchemaErrorTransform and HttpApiSchema.asJson({ contentType }). But every project then writes its own schema, picks its own type, title and status defaults, and has to get the RFC's parsing rules right. For example, §3.1 says a member with the wrong JSON type is ignored, not rejected. #5367 asked for this in v3 and was closed with a workaround that re-encoded response bodies in a middleware. The people in that thread noted that the OpenAPI output then had to be patched as well.

Proposal

  1. A ProblemDetails value and Schema:
    • type defaults to about:blank.
    • status, title, detail and instance are optional.
    • Unknown members are kept as extensions.
    • It decodes leniently, as §3.1 requires, and encodes canonically.
    • A way to declare a typed problem: a fixed type URI with typed extension members, usable as an HttpApi error schema with the right status, media type and OpenAPI entry.
  2. An opt-in that renders HttpApi's own errors (decode failures and the built-ins) as Problem Details.
  3. HttpApiClient decodes application/problem+json responses into the declared problem type.
// names illustrative
class OutOfCredit extends ProblemDetails.Type("https://example.com/probs/out-of-credit", {
  status: 403,
  balance: Schema.Number
}) {}

HttpApiEndpoint.post("buy", "/buy", { error: OutOfCredit })

Why in Effect

HttpApi owns both the mapping from errors to responses and the OpenAPI output, so this is the one place where it can be done without post-processing bodies and patching the spec. The format is widely supported elsewhere: ASP.NET Core (AddProblemDetails), Spring (ProblemDetail), and Rust's http-api-problem crate.

Scope

In scope:

  • The value and Schema, typed problems, opt-in rendering, OpenAPI output and client decoding.

Out of scope:

  • application/problem+xml.
  • Changing the default empty-body behaviour without an opt-in.

Open questions

  • Should this live in effect/http, so it can be used without HttpApi, or in effect/http-api?
  • How much should a decode failure reveal by default? The failing path and message help clients, but they also expose details of the schema.
主要语言
TypeScript
星标
16.7k
派生
808
平均合并
10 小时 7 分钟
30 天内合并 PR
808

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

Effect-TS/effect 的其他 Issue

查看 Effect-TS/effect 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。