Strapi v4自定义搜索端点404错误及路由控制器配置问询

一、404 Not Found 原因排查 #

出现404的核心原因通常是Strapi未正确加载自定义路由/控制器，具体可能是以下几点：

1. 文件命名/路径不符合Strapi v4规范：Strapi v4会根据内容类型的文件夹结构自动注册路由，路由文件需放在src/api/reserve/routes/reserve.js（而非reserves.js），控制器文件需对应src/api/reserve/controllers/reserve.js，文件名需与内容类型单数名一致。
2. 修改配置后未重启Strapi：路由、控制器的修改不会触发热重载，必须重启开发服务器才能生效。
3. 路由注册日志未验证：启动Strapi时未检查日志是否输出自定义路由的注册信息，无法确认路由是否被加载。

二、自定义搜索端点的正确配置步骤 #

1. 确认文件结构 #

确保你的文件结构严格遵循Strapi v4规范：

src/
└── api/
    └── reserve/
        ├── controllers/
        │   └── reserve.js  # 控制器文件
        ├── routes/
        │   └── reserve.js  # 路由文件
        └── ...（其他内容类型文件）

2. 控制器代码优化 #

将控制器代码写入src/api/reserve/controllers/reserve.js，考虑到code是唯一值，用findOne替代findMany更高效：

const { createCoreController } = require('@strapi/strapi').factories;

module.exports = createCoreController('api::reserve.reserve', ({ strapi }) => ({
  async search(ctx) {
    try {
      const { code } = ctx.query;
      if (!code) {
        return ctx.badRequest('کد پیگیری مورد نیاز است.');
      }

      // 按唯一code查询单条记录
      const entity = await strapi.entityService.findOne('api::reserve.reserve', {
        filters: { code },
      });

      if (!entity) {
        return ctx.notFound('هیچ رزروی با این کد پیگیری یافت نشد.');
      }

      // 返回与Strapi默认API格式一致的标准化响应
      const sanitizedEntity = await this.sanitizeOutput(entity, ctx);
      return this.transformResponse(sanitizedEntity);
    } catch (err) {
      return ctx.internalServerError('خطا در پردازش درخواست');
    }
  },
}));

3. 路由代码修正 #

将路由代码写入src/api/reserve/routes/reserve.js，确保路径、handler映射正确：

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/reserves/search',
      handler: 'reserve.search',
      config: {
        auth: false,
        // 可选：添加参数验证，确保code必填
        validate: {
          query: {
            code: { type: 'string', required: true },
          },
        },
      },
    },
  ],
};

4. 验证与测试 #

1. 重启Strapi开发服务器：执行npm run develop或yarn develop。
2. 检查启动日志，确认自定义路由已注册：

   [2024-xx-xx xx:xx:xx] debug GET /api/reserves/search (reserve.search)
   

3. 发送测试请求：GET https://example.com/api/reserves/search?code=12962，此时应返回对应记录或正确的错误提示。

三、遗漏的配置项说明 #

除了文件结构和重启服务，还需注意：

• 内容类型权限：虽然路由设置了auth: false，但需确保reserve内容类型的find权限已开启（在Strapi后台「设置→角色与权限→公共角色」中配置）。
• 参数类型匹配：如果code字段是数字类型，需确保请求参数传递的是数字格式（或Strapi会自动类型转换，建议保持一致）。

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