MenuController API 文档

🧩 方法概览

该控制器提供了两个核心方法，用于根据不同场景获取菜单数据：

方法名称	路由	请求方式	核心区别（查询条件）
actionGetNavMenu	/menu/getNavMenu	GET	is_menu_show = 1 AND is_show = 1
actionGetNav	/menu/getNav	GET	is_show = 1

关键区别：actionGetNavMenu 用于获取需要在主导航栏中显示的菜单项，因此条件更严格（is_menu_show 必须为1）。而 actionGetNav 用于获取所有处于显示状态的菜单项，适用于侧边栏、面包屑等场景。

1. 获取导航菜单 (actionGetNavMenu)

此接口用于获取主导航菜单。它返回指定父级菜单下所有已启用、已标记为在导航中显示的子菜单项，并按指定顺序排列。

接口信息

端点地址：https://hapi.caixiangxiang.com/menu/getNavMenu
请求方式：GET
认证要求：是（通常需要在HTTP头中包含 Authorization: Bearer <token>）

请求参数

参数名	位置	类型	必填	默认值	说明
parent_id	Query String	Integer	否	0	父级菜单的ID。传0或忽略此参数则获取所有一级菜单。

请求示例

获取一级主导航

curl -X GET "https://hapi.caixiangxiang.com/menu/getNavMenu?parent_id=0" \
  -H "Authorization: Bearer your_access_token_here"

获取ID为5的菜单下的子主导航

curl -X GET "https://hapi.caixiangxiang.com/menu/getNavMenu?parent_id=5" \
  -H "Authorization: Bearer your_access_token_here"

成功响应 (HTTP 200)

响应体结构：

{
  "statusCode": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "首页",
      "parent_id": 0,
      "level": 1,
      "url": "/home",
      "sort_order": 1,
      "create_time": "2024-01-01 10:00:00"
    },
    {
      "id": 2,
      "name": "产品中心",
      "parent_id": 0,
      "level": 1,
      "url": "/products",
      "sort_order": 2,
      "create_time": "2024-01-01 10:00:00"
    }
  ]
}

返回字段说明：

字段	类型	说明
statusCode	Integer	状态码，200表示成功
message	String	成功的消息描述
data	Array[Object]	菜单对象列表
data[].id	Integer	菜单项的唯一标识
data[].name	String	菜单项的显示名称
data[].parent_id	Integer	父级菜单的ID，0表示这是一级菜单
data[].level	Integer	菜单层级（1: 一级菜单, 2: 二级菜单, ...）
data[].url	String	菜单项对应的链接地址
data[].sort_order	Integer	排序号，数值越小越靠前
data[].create_time	String	菜单项的创建时间

错误响应

HTTP状态码	错误代码	消息	可能原因
500	-	"获取导航菜单失败"	服务器内部错误，如数据库连接失败

2. 获取导航 (actionGetNav)

此接口用于获取所有显示的菜单，不限于主导航。它返回指定父级菜单下所有已启用（无论is_menu_show为何值）的子菜单项。

接口信息

端点地址：https://hapi.caixiangxiang.com/menu/getNav
请求方式：GET
认证要求：是

请求参数

参数名	位置	类型	必填	默认值	说明
parent_id	Query String	Integer	否	0	父级菜单的ID。传0或忽略此参数则获取所有一级菜单。

请求示例

获取所有一级菜单（包括不在主导航显示的）

curl -X GET "https://hapi.caixiangxiang.com/menu/getNav?parent_id=0" \
  -H "Authorization: Bearer your_access_token_here"

成功响应 (HTTP 200)

响应体结构：

{
  "statusCode": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "首页",
      "parent_id": 0,
      "level": 1,
      "url": "/home",
      "sort_order": 1,
      "is_menu_show": 1,
      "create_time": "2024-01-01 10:00:00"
    },
    {
      "id": 3,
      "name": "网站地图",
      "parent_id": 0,
      "level": 1,
      "url": "/sitemap",
      "sort_order": 99,
      "is_menu_show": 0,
      "create_time": "2024-01-01 10:00:00"
    }
  ]
}

返回字段说明（与actionGetNavMenu基本相同，但增加了一个字段）：

字段	类型	说明
...	...	其他字段同上
data[].is_menu_show	Integer	额外字段：标记此菜单是否在主导航显示（1: 显示, 0: 不显示）

错误响应

HTTP状态码	错误代码	消息	可能原因
500	-	"获取导航失败"	服务器内部错误

⚠️ 通用说明与最佳实践

排序规则

两个接口返回的菜单列表均按 sort_order 升序排列（数值越小越靠前），如果排序号相同，则按 id 升序排列。

数据过滤

两个接口均自动过滤已删除的数据（is_del = 0）。
核心区别在于 actionGetNavMenu 要求 is_menu_show = 1，而 actionGetNav 不要求。

使用场景建议

网站主导航栏：使用 actionGetNavMenu，因为它只返回希望在主导航中显示的菜单。
站点地图、页脚链接、侧边栏导航：使用 actionGetNav，因为它返回所有可用的菜单项，信息更全面。
构建树形菜单：可以递归调用这些接口（将返回的菜单项id作为新的parent_id传入）来构建完整的菜单树。

错误处理

客户端调用时，应始终检查响应的 statusCode。非200状态码表示请求未成功，应根据 message 字段进行相应的用户提示或日志记录。

希望这份详细的文档能帮助您更好地集成和使用菜单接口！