OneUptime API Reference 源码解析get-item 单条记录请求ItemRequest的构造、select 字段与多语言代码示例生成【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文围绕 OneUptime 开源监控平台的 API 参考站点APIReference中的 ItemRequest.md 文档展开完整解析get-item按 ID 获取单条记录接口的请求头、请求体select字段的语义与默认行为并结合 Model.ts、CodeExampleGenerator.ts 等源码说明这些请求描述是如何被读取、缓存并最终渲染为 12 种编程语言代码示例的帮助读者既会用该接口、又看得懂文档站背后的实现机制。一、ItemRequest 文档的定位get-item 接口的请求说明ItemRequest.md是 OneUptime API 参考功能集中的一组“模型级请求/响应说明”文件之一。同目录下还有 ListRequest.md、CountRequest.md、UpdateRequest.md、CreateRequest.md、DeleteRequest.md 以及对应的*Response.md文件分别对应各模型Monitor、Contact 等CRUD 接口的请求与响应约定。原始文档内容非常精简核心信息如下这是该文档的完整语义下文将逐项展开请求头Request HeadersApiKey: {secret-api-key} ProjectID: {project-id}请求体Request Body{ select: { // select object (optional, if left optional itll only fetch ID). } }两行请求头 一个可选的select对象构成了get-item请求的全部约定。下面结合渲染该文档的模板和请求生成器源码把每一部分讲透。二、请求头详解ApiKey 与 ProjectID2.1 两个请求头的职责ApiKey: {secret-api-key}携带项目密钥secret api key完成身份认证。{secret-api-key}是占位符实际调用时需要替换为在 OneUptime 中为项目创建的真实密钥。从源码看示例生成器统一用YOUR_API_KEY作为占位符输出到文档页面见 CodeExampleGenerator.ts 中的API_KEY_PLACEHOLDER常量定义。ProjectID: {project-id}指定目标项目 ID。由于一个 OneUptime 实例可以管理多个项目读取密钥之外的记录时通过该头声明作用域。2.2 文档页面上的请求头预览API 参考页面渲染“请求预览”时展示的 Headers 区块由CodeExampleGenerator的generateRequestPreview方法生成固定输出两行Content-Type: application/json ApiKey: YOUR_API_KEY见 CodeExampleGenerator.ts。注意一个细节运行时生成的示例只带Content-Type与ApiKey两个头而原始ItemRequest.md中还额外声明了ProjectID头——也就是说静态文档中的请求头约定比动态生成的代码示例更完整实际调用时两者都应视为可用以接口实际接受为准。三、请求体详解select 字段与“只取 ID”的默认行为3.1 select 的对象结构与示例请求体中唯一约定的字段是select它是一个字段选择对象键为要返回的列名值为true表示选中。同目录 Select.md 给出了更具体的 select 写法示例{ select: { name: true // other fields } }3.2 省略 select 时的默认行为ItemRequest.md中那行注释是关键约定select object (optional, if left optional itll only fetch ID).即select是可选字段如果请求体中不带select或留空get-item只会返回记录的 ID 字段。这是一个显式的“最小返回”约定用于在只需要确认某条记录存在、或只需要拿到_id做后续操作时减少传输量。3.3 文档页面如何呈现这一约定在模型文档页模板 model.ejs 的 “Get Item” 小节中可以清楚看到请求参数表的定义必填查询参数idtext 类型即记录 ID可选请求体selectselect 数据类型并附说明“用于指定要返回的字段”链接到数据类型文档的 select 章节/reference/{lang}/data-types#select。模板中该小节通过code-tabs局部模板渲染请求示例端点为{apiPath}/:id/get-item方法标注为GET与POST两种见 model.ejs 的methods: [GET, POST]以及第 251 行requestType: POST的请求体示例。请求体示例则由运行时的simpleSelectExample对象注入通常最多 5 个具有读权限的字段生成逻辑见 Model.ts。3.4 配套响应ItemResponse.mdget-item的响应约定在同目录 ItemResponse.md 中返回一个 JSON 对象包含_id字段与其余被 select 选中的字段。模板侧的响应示例由simpleResponseExample生成——其中_id是每次页面渲染时新生成的示例 ObjectID见 Model.ts字段值则根据列类型自动生成ObjectId、布尔、数字、日期、邮箱、URL、颜色、Markdown、JSON、数组等都有对应的默认示例值规则见 Model.ts 的getDefaultExampleForType。四、端到端请求示例一次真实的 get-item 调用综合ItemRequest.md的约定与CodeExampleGenerator的输出格式基础地址为https://oneuptime.com见 CodeExampleGenerator.ts一次完整的get-item调用形如curl -X POST https://oneuptime.com/api/v1/{crud-api-path}/{record-id}/get-item \ -H Content-Type: application/json \ -H ApiKey: YOUR_API_KEY \ -H ProjectID: {project-id} \ -d { select: { name: true } }其中{crud-api-path}由模型自身的crudApiPath决定文档站拼接 API 路径的方式见 Model.tsAppApiRoute model.crudApiPath。等价的 Python 调用与生成器输出同构参考 CodeExampleGenerator.ts 的 Python 模板import requests url https://oneuptime.com/api/v1/{crud-api-path}/{record-id}/get-item headers { Content-Type: application/json, ApiKey: YOUR_API_KEY, ProjectID: {project-id} } payload { select: { name: True } } response requests.post(url, jsonpayload, headersheaders) print(response.json())要点回顾要素取值说明方法POST文档页同时标注 GET 可用见 model.ejs端点{apiPath}/:id/get-itemid为必填的记录 ID头ApiKey项目密钥身份认证必填头ProjectID项目 ID作用域标识ItemRequest.md中约定体select字段选择对象值为true的列被返回可选省略时只返回 ID五、源码链路ItemRequest.md 如何进入 API 参考页面5.1 文件读取与缓存ItemRequest.md并非直接被模板include而是由模型文档服务在渲染前读入页面数据。在 Model.ts 中// Cache the item request data pageData[itemRequest] await LocalCache.getOrSetString( model, item-request, async () { // Read the item request data from a file return await LocalFile.read(${CodeExamplesPath}/Model/ItemRequest.md); }, );要点路径来自集中配置CodeExamplesPath定义在 Config.ts容器内为/usr/src/app/FeatureSet/APIReference/CodeExamples仓库中对应App/FeatureSet/APIReference/CodeExamples/目录。修改这份 md 文件即直接改变文档站的静态请求说明无需改代码。LocalCache.getOrSetString做进程内缓存以(model, item-request)为键首次渲染读盘后续命中缓存同目录其余 9 份*.mdlist/count/create/update/delete 的 request/response均走完全相同的模式Model.ts。5.2 页面请求示例的动态生成从源码结构看pageData[itemRequest]与其余*Request/*Response字符串一并注入pages/index渲染上下文Model.ts而模型页 get-item 小节中实际展示的“请求代码块”来自运行时生成的codeExamples.getItem——由generateApiCodeExamples中这段调用产生Model.ts// Get item endpoint const getItemExamples: CodeExamples CodeExampleGenerator.generate({ method: POST, endpoint: ${apiPath}/${exampleObjectID}/get-item, body: { select: exampleObjects.simpleSelectExample, }, description: Get a single item by ID, });其中simpleSelectExample的挑选规则值得注意Model.ts按“有示例值优先 → 必填优先 → 字母序”排序列只取前 5 个具有读权限permissions.read非空的列值为true同时跳过计算列。因此文档页上每个模型展示的 select 示例都严格符合该模型的列级访问控制不会出现无权限字段。5.3 从请求参数到 12 种语言代码CodeExampleGenerator.generateCodeExampleGenerator.ts接收method / endpoint / body / description四个参数一次性产出 12 个产物请求预览Headers Body 两段文本、cURL、JavaScript、TypeScript、Python、Go、Java、C#、PHP、Ruby、Rust、PowerShell。各语言模板对 body 的处理策略不同例如Python 用jsonToPython把 JSON 对象转成 dict 字面量true → True、null → NoneGo 用map[string]interface{}加json.MarshalRust 用serde_json::json!宏PowerShell 用ConvertTo-Json -Depth 10。渲染端由 code-tabs.ejs 完成它为每个语言生成一个 tab容器 ID 由“标题 方法 请求 URL”做 djb2 哈希得到同一页面重复渲染可得到稳定结构模板注释中明确这是为了可测试性并内置复制按钮与键盘可访问性roletablist、aria-selected等见 code-tabs.ejs 与 #L54-L90。因此用户在 API 参考页看到的“Get item”请求卡片就是ItemRequest.md声明的select约定 动态示例字段 静态生成器模板三者叠加的产物。六、小结从一份 12 行文档到一套文档生成管线ItemRequest.md用 12 行文本完整定义了get-item的调用契约ApiKeyProjectID两个请求头以及“可选select、省略则只取 ID”的请求体规则Model.ts 将该文件经LocalFile读取、LocalCache缓存后注入渲染上下文并依据模型列元数据与访问控制动态生成 select 示例与exampleObjectIDCodeExampleGenerator.ts 把同一请求参数展开为 12 种语言的可用代码code-tabs.ejs 负责 tab 化渲染与复制交互。理解这条链路后开发者做两件事都变得直接调用接口时按第二、三、四节的头与体约定即可维护文档时修改App/FeatureSet/APIReference/CodeExamples/Model/下对应 md 文件即可更新文档站的静态请求说明而各模型页面展示的具体字段示例则由 Model.ts 中的元数据驱动逻辑自动跟进无需手工维护。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考