Open-Falcon（falcon-plus）指定用户资料更新 API 实战指南：PUT /api/v1/user/u/:uid-平芜编程栈

运维观测
指标监控
告警

【免费下载链接】falcon-plus

An open-source and enterprise-level monitoring system.

项目地址：https://gitcode.com/gh_mirrors/fa/falcon-plus

本指南基于 Open-Falcon（falcon-plus）开源监控系统的 API 文档 docs/_posts/User/2019-04-14-update-specific-user.md，深入讲解如何通过PUT /api/v1/user/u/:uid接口按用户 ID 更新指定用户的姓名、邮箱、IM、电话与 QQ 等资料字段。读完本文，你将掌握该接口的完整请求格式、鉴权方式、字段约束、典型返回与常见错误处理，并能结合源码理解其底层实现（gorm 更新逻辑、危险字符校验、会话校验中间件），为二次开发或运维集成提供可靠依据。

接口概述

PUT /api/v1/user/u/:uid是 falcon-plus 的 API 模块（modules/api）提供的用户管理接口之一，用于按用户 ID 精确更新某个已存在用户的资料信息。与之同属"用户更新"系列的其他接口包括：

接口	用途	说明
`PUT /api/v1/user/u/:uid`	按 ID 更新指定用户资料	本文主角，需要登录会话
`PUT /api/v1/user/update`	更新当前登录用户资料	见 docs/_posts/User/2017-01-01-user_update.md
`PUT /api/v1/user/cgpasswd`	修改当前用户密码	见 docs/_posts/User/2017-01-01-user_change_password.md
`PUT /api/v1/admin/change_user_profile`	管理员修改任意用户资料	需管理员权限

从源码结构看，这些接口均注册于 user_routes.go：u := r.Group("/api/v1/user")定义了用户相关路由，其中authapi.PUT("/u/:uid", UpdateUser)（见 user_routes.go）即本文目标接口，路由注册后挂载了utils.AuthSessionMidd会话鉴权中间件，因此调用前必须先完成登录并持有有效会话。

请求说明

请求方法与路径

方法：PUT
路径：/api/v1/user/u/:uid
路径参数：uid（用户 ID，整数）。原文档 Front Matter 中apiurl: '/api/v1/user/u/:uid'表明该参数为必填路径变量。

会话（Session）要求

原文档明确标注* [Session](#/authentication) Required，即该接口必须携带有效登录会话。在 falcon-plus 中，会话通过请求头Apitoken传递，其值为 JSON 格式的{"name":"...","sig":"..."}，name为用户名、sig为登录后下发的会话签名。具体校验逻辑参见 session.go 的SessionChecking函数：

从请求头读取Apitoken并解析出name与sig；
若配置了default_token且sig与之匹配，直接放行（用于服务端内部调用）；
否则在uic库的user表中按name查用户，再在session表中按sig + uid匹配会话记录，匹配成功才认证通过。

认证中间件 auth_middle.go 会在校验失败时返回401 Unauthorized并中断请求。注意，配置文件中的skip_auth若为true会跳过该校验（仅限调试/内网环境使用），生产环境应保持默认关闭。完整登录流程可参考 docs/_posts/User/2017-01-01-user_login.md。

请求体（Request Body）

原文档给出的请求体示例如下：

{ "cnname": "翱鶚Test", "email": "root123@cepave.com", "im": "44955834958", "phone": "99999999999", "qq": "904394234239" }

请求体字段与源码中 user_controller.go 定义的APIUserUpdateInput结构体一一对应：

字段	JSON 键	必填	说明
Cnname	`cnname`	是（`binding:"required"`）	用户中文姓名
Email	`email`	是（`binding:"required"`）	用户邮箱
Phone	`phone`	否	手机号
IM	`im`	否	即时通讯账号
QQ	`qq`	否	QQ 号

需要特别指出：该接口不接收name与password字段。用户名与密码不属于可在此更新的资料范畴——APIUserUpdateInput中并未定义这两个字段，且底层更新语句（见下文）只写入cnname、email、phone、im、qq五列。若需要修改密码，应使用PUT /api/v1/user/cgpasswd（本人）或管理员的change_user_passwd接口。

响应说明

成功响应

原文档记录的成功响应为：

Status: 200 {"message":"user info updated"}

该格式由 simple_reponse.go 的JSONR统一封装：当以字符串形式返回且状态码为 200 时，响应体被包装为{"message":"..."}；当返回错误时则为{"error":"..."}。

失败响应

原文档提示错误响应可参见 docs/_posts/2017-01-01-response-status-codes.md。结合源码实现，本接口可能返回的错误场景包括：

场景	HTTP 状态码	响应体 error 内容
会话无效 / 未登录	401	会话校验相关错误（由鉴权中间件拦截）
缺少`uid`路径参数	400	`user id is missing`
`uid`不是合法整数	400	类型转换错误
请求体 JSON 解析失败或必填字段缺失	417（`StatusExpectationFailed`）	字段校验错误（如`cnname`/`email`缺失）
`cnname`包含危险字符	400	`name pattern is invalid`
目标用户不存在	400	`user does not exist`
数据库更新失败	417	gorm 返回的底层错误

以上分支逐一对应 UpdateUser 函数中的校验与错误处理逻辑，具体可对照源码阅读。

完整调用示例（curl）

综合原文档请求格式与上述鉴权要求，一个完整的调用示例如下：

curl -X PUT "http://<api_host>:8080/api/v1/user/u/4" \ -H "Content-Type: application/json" \ -H 'Apitoken: {"name":"root","sig":"427d6803b78311e68afd0242ac130006"}' \ -d '{ "cnname": "翱鶚Test", "email": "root123@cepave.com", "im": "44955834958", "phone": "99999999999", "qq": "904394234239" }'

<api_host>:8080为 API 模块服务地址（默认监听端口见 cfg.example.json）；
Apitoken需替换为实际登录后获得的{"name":...,"sig":...}；
:uid可先通过GET /api/v1/user/u/:uid（见 docs/_posts/User/2017-01-01-user_get_info_by_id.md）或用户列表接口确认目标用户 ID。

源码实现深度解析

处理流程

该接口的核心实现为 user_controller.go 中的UpdateUser函数，其处理链路如下：

解析路径参数：通过c.Params.ByName("uid")取得uid，为空则返回user id is missing，并用strconv.Atoi转换为整数；
绑定并校验请求体：c.BindJSON(&inputs)解析 JSON，缺失必填字段会触发binding:"required"校验并返回 417；随后调用utils.HasDangerousCharacters(inputs.Cnname)对中文姓名做危险字符检查，不合法返回 400；
确认目标用户存在：db.Uic.Table("user").Where("id = ?", uid).Scan(&user)，若user.ID == 0返回user does not exist；
执行更新：构造待更新字段 map 后调用 gorm 的Update：

uuser := map[string]interface{}{ "Cnname": inputs.Cnname, "Email": inputs.Email, "Phone": inputs.Phone, "IM": inputs.IM, "QQ": inputs.QQ, } dt := db.Uic.Model(&user).Where("id = ?", uid).Update(uuser)

返回结果：更新成功返回h.JSONR(c, "user info updated")，即200 {"message":"user info updated"}。

数据表与模型映射

用户资料落库在uic库的user表（建表脚本见 scripts/mysql/db_schema/1_uic-db-schema.sql）。对应模型定义在 modules/api/app/model/uic/user.go：

type User struct { ID int64 `json:"id"` Name string `json:"name"` Cnname string `json:"cnname"` Passwd string `json:"-"` Email string `json:"email"` Phone string `json:"phone"` IM string `json:"im" gorm:"column:im"` QQ string `json:"qq" gorm:"column:qq"` Role int `json:"role"` }

可以看到Passwd的 JSON tag 为-（不出现在 API 响应中），Role字段则用于权限判断（Role == 2为超级管理员，Role == 1为管理员，详见同文件的IsAdmin/IsSuperAdmin方法）。本文接口只更新资料字段，不改动Name、Passwd、Role。

与"更新当前用户"及"管理员更新"的关系

PUT /api/v1/user/u/:uid（UpdateUser）：按 ID 更新任意用户，调用者需具备有效会话。从源码看，该接口并未显式校验调用者是否为管理员——其定位更偏向"平台内部/受信调用方按 ID 更新"，配合 API 网关或上层权限控制使用；
PUT /api/v1/user/update（UpdateCurrentUser，见 user_controller.go）：仅允许更新当前登录用户自身资料，通过会话中的name定位用户，普通用户自助改资料的推荐入口；
PUT /api/v1/admin/change_user_profile（AdminChangeUserProfile，见 user_controller.go）：显式校验IsAdmin()权限，管理员批量维护用户资料的首选。

三者共用相同的五字段更新集合与{"message":"..."}风格响应，区别仅在于"按 ID / 按当前会话 / 按请求体 user_id"三种定位用户的方式与权限约束。

实战注意事项

先查后改：建议先调用GET /api/v1/user/u/:uid或用户列表接口确认uid存在，避免直接触发user does not exist（400）；
必填字段不可省略：cnname与email缺失时请求会被 gorm-validator 拦截并返回 417 及字段错误明细；
中文姓名安全校验：cnname需避免包含危险字符，否则返回name pattern is invalid；
会话有效期：登录接口创建的 session 默认有效期约 30 天（见 CreateUser 中的 session 创建逻辑），长期运行的集成脚本需关注sig过期问题，可配置default_token供服务端内部调用；
API 文档配套：更多用户相关接口的完整请求/响应示例可参考 docs/doc/user.html，用户登录、登出、鉴权等流程见 docs/_posts/2017-01-01-authentication.md。

小结

PUT /api/v1/user/u/:uid是 falcon-plus 用户管理中"按 ID 精准更新用户资料"的标准接口：携带Apitoken会话、以uid定位用户、提交cnname/email/phone/im/qq五个字段即可完成更新，成功返回200 {"message":"user info updated"}。通过本文的源码级剖析，你可以清楚掌握其鉴权链路、字段约束与错误语义，从而在监控平台用户治理、账号信息同步等实际场景中正确使用该接口。