Blazor Boilerplate中Breeze ApiClient JSON解析错误求助

错误本质 #

Newtonsoft.Json.JsonReaderException: Unexpected character encountered while parsing value: < 是典型的接口返回格式不匹配错误：Breeze.Sharp客户端预期拿到JSON响应，实际拿到的是<开头的HTML内容（通常是404页、500服务异常页、登录跳转页、开发环境错误详情页），JSON解析器读到HTML标签起始符直接报错。
该问题在新增独立数据库、配套Controller和Persistence Manager后出现，核心原因是Breeze客户端与新数据源的服务端配置不匹配，和页面、ApiClient中写的查询逻辑无关。

排查修复步骤（按优先级从高到低） #

1. 检查EntityManager是否绑定了正确的服务端路由 #

Blazor Boilerplate默认注入的EntityManager是绑定主数据上下文的/breeze/data路由的，第二数据源如果用了独立的Controller路由，必须新建独立的EntityManager实例配置对应路由，不能直接复用主库的EntityManager。

• 检查你新建的第二数据源Breeze Controller路由，不要和默认的/breeze/data冲突，比如可以给第二数据源Controller标注[BreezeQueryFilter, Route("breeze/seconddb")]
• 为第二数据源单独初始化EntityManager，将服务端地址指向新Controller的路由，查询Customer数据时必须使用这个新的EntityManager实例，否则请求会发到主库Controller，主库没有对应实体配置直接返回404错误页。

2. 验证新Controller和Persistence Manager配置有效性 #

直接在浏览器访问新数据源的元数据接口，比如https://你的站点地址/breeze/seconddb/Metadata：

• 如果正常返回JSON格式的元数据，说明Controller路由、Persistence Manager基础配置正常
• 如果返回HTML错误页，直接查看页面内的服务端错误信息修复，常见问题包括：
  • Controller没有继承BreezeController基类
  • 第二数据库连接字符串配置错误，上下文初始化失败
  • Persistence Manager中没有注册Customer实体的映射关系
  • 没有公开对应元数据、查询、保存的接口方法

3. 检查实体集名称匹配 #

客户端查询时From("Customers")的实体集名称，必须和服务端Persistence Manager中配置的实体集名称大小写完全一致，名称不匹配会直接返回404。
如果新数据源用了独立的EntityManager，初始化时要先拉取对应数据源的元数据，或者手动注册Customer实体类型和服务端实体集的映射关系。

4. 快速定位真实错误的方法 #

调试时打开浏览器开发者工具的「网络」面板，找到Breeze发起的查询请求，直接查看响应内容：

• 响应状态码404：路由不匹配，检查EntityManager地址、Controller路由配置、实体集名称
• 响应状态码500：服务端执行报错，根据响应里的异常堆栈修复，常见是数据库连接失败、实体映射配置错误
• 响应状态码302跳转到登录页：新Controller的路由没有加入授权白名单，请求被重定向到登录页返回HTML

内容的提问来源于stack exchange，提问作者Buda56