MangoFanFanw/NyaHome
1
1
Fork 0
Code Issues 2 Pull Requests Packages Projects 1 Releases Wiki Activity

style: 一些复杂而综合的细节修正

Browse Source
This commit is contained in:
芒果帆帆
2026-05-25 21:11:29 +08:00
parent 8efb55827c
commit ff2074b400
8 changed files with 97 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/nyahome/cli/openapi_docstring.py
+44 -80
View File
@@ -38,17 +38,21 @@ import inspect
import logging
from typing import Any, Dict, Optional, Set
from docstring_parser import DocstringStyle, ParseError, parse
from docstring_parser import Docstring, DocstringStyle, ParseError, parse
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
logger = logging.getLogger(__name__)
def _parse_docstring(
func: Any, style: DocstringStyle = DocstringStyle.AUTO
) -> Optional[Any]:
"""解析函数的 Google Style docstring，失败时返回 None。"""
def _parse_docstring(func: Any, style: DocstringStyle = DocstringStyle.AUTO) -> Optional[Docstring]: # noqa ANN401 有意为之
"""
解析函数的 Google Style docstring，失败时返回 None。
Returns:
成功解析时返回 docstring_parser.Docstring。
失败时返回 None。
"""
doc = inspect.getdoc(func)
if not doc:
return None
@@ -67,8 +71,13 @@ def _parse_docstring(
return None
def _build_param_lookup(parsed_doc: Any) -> Dict[str, str]:
"""从解析后的 docstring 构建 {参数名: 描述} 映射。"""
def _build_param_lookup(parsed_doc: Docstring) -> Dict[str, str]:
"""
从解析后的 docstring 构建 {参数名: 描述} 映射。
Returns:
{参数名: 描述}
"""
lookup: Dict[str, str] = {}
for param in getattr(parsed_doc, "params", []) or []:
name = getattr(param, "arg_name", None)
@@ -79,8 +88,13 @@ def _build_param_lookup(parsed_doc: Any) -> Dict[str, str]:
return lookup
def _build_returns_description(parsed_doc: Any) -> Optional[str]:
"""从解析后的 docstring 构建返回值描述。"""
def _build_returns_description(parsed_doc: Docstring) -> Optional[str]:
"""
从解析后的 docstring 构建返回值描述。
Returns:
可能的字符串为返回值描述。
"""
ret = getattr(parsed_doc, "returns", None)
if not ret:
return None
@@ -91,8 +105,13 @@ def _build_returns_description(parsed_doc: Any) -> Optional[str]:
return desc or None
def _build_raises_description(parsed_doc: Any) -> Optional[str]:
"""从解析后的 docstring 构建异常描述（Markdown 列表）。"""
def _build_raises_description(parsed_doc: Docstring) -> Optional[str]:
"""
从解析后的 docstring 构建异常描述（Markdown 列表）。
Returns:
可能的字符串为异常描述。
"""
raises = getattr(parsed_doc, "raises", None)
if not raises:
return None
@@ -110,7 +129,12 @@ def _build_raises_description(parsed_doc: Any) -> Optional[str]:
def _dedent_description(text: str) -> str:
"""清理 docstring 描述中的多余缩进，保留段落结构。"""
"""
清理 docstring 描述中的多余缩进，保留段落结构。
Returns:
docstring 字符串
"""
if not text:
return ""
lines = text.splitlines()
@@ -123,10 +147,11 @@ def _dedent_description(text: str) -> str:
return "\n".join(cleaned).strip()
def _get_clean_operation_description(parsed_doc: Any) -> str:
def _get_clean_operation_description(parsed_doc: Docstring) -> str:
"""
生成干净的 operation description。
Returns:
策略：保留 summary + long_description，去掉 Args/Returns/Raises 等机器块。
"""
parts: list[str] = []
@@ -174,7 +199,7 @@ def _inject_schema_properties(
properties = schema.get("properties")
if isinstance(properties, dict):
for prop_name, prop_schema in properties.items():
if prop_name in param_lookup:
if prop_name in param_lookup: # noqa SIM102
# 只有当 docstring 描述非空时才写入
if param_lookup[prop_name]:
prop_schema["description"] = param_lookup[prop_name]
@@ -220,8 +245,8 @@ def enrich_openapi_from_docstrings(
解析风格。团队统一用 Google 时可显式传入 ``DocstringStyle.GOOGLE``。
"""
# 保存原始的 openapi 函数（如果有）
original_openapi = app.openapi
# 可选择保存原始的 openapi 函数（如果有）
# original_openapi = app.openapi
def custom_openapi() -> Dict[str, Any]:
# 如果已经有缓存，直接返回
@@ -284,9 +309,7 @@ def enrich_openapi_from_docstrings(
for media_obj in content.values():
schema = media_obj.get("schema", {})
if schema:
_inject_schema_properties(
schema, param_lookup, openapi_schema=openapi_schema
)
_inject_schema_properties(schema, param_lookup, openapi_schema=openapi_schema)
# ---------- 4. 注入返回值描述 ----------
if returns_desc:
@@ -300,9 +323,7 @@ def enrich_openapi_from_docstrings(
if schema and not schema.get("description"):
schema["description"] = returns_desc
# 递归注入 schema 内部字段
_inject_schema_properties(
schema, param_lookup, openapi_schema=openapi_schema
)
_inject_schema_properties(schema, param_lookup, openapi_schema=openapi_schema)
# ---------- 5. 异常描述追加 ----------
if append_raises_to_description and raises_desc:
@@ -315,61 +336,4 @@ def enrich_openapi_from_docstrings(
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
# =============================================================================
# 完整使用示例
# =============================================================================
if __name__ == "__main__":
import json
from typing import Annotated, Optional
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel, Field
# ---------- 定义 DTO ----------
class EditChatDto(BaseModel):
old_message: str = Field(..., description="原始消息内容")
new_message: str = Field(..., description="修改后的消息内容")
change: str = Field(..., description="变更类型")
class ReturnDto(BaseModel):
result: str = Field(..., description="操作结果")
content: str = Field(..., description="最新聊天记录内容")
# ---------- 创建应用 ----------
app = FastAPI(title="Chatroom API", version="1.0.0")
# 启用 docstring 增强（必须在注册路由之前或之后都可以，但要在生成 schema 之前）
enrich_openapi_from_docstrings(app)
# ---------- 注册路由 ----------
@app.post("/api/chatroom/{id_}/chat/edit/", response_model=ReturnDto)
async def edit_chatroom_chat(
id_: Annotated[str, Path(description="聊天室 ID")],
body: EditChatDto,
force: Annotated[Optional[bool], Query(description="是否强制覆盖")] = None,
) -> ReturnDto:
"""编辑聊天室消息。
此端点不负责调用 AI 生成输出，而是用于修改一条已经保存在聊天记录中的消息。
前端调用后应使用返回的 content 刷新当前聊天室界面。
Args:
id_: 聊天室唯一标识符，UUID 格式。
body: 编辑请求体，包含旧消息、新消息和变更类型。
force: 是否跳过冲突检测直接覆盖。
Returns:
ReturnDto: 操作结果，其中 result 字段表示状态，content 字段为最新聊天记录。
Raises:
HTTPException: 404 表明未找到聊天室。
HTTPException: 400 表明聊天记录匹配失败，未更新。
"""
return ReturnDto(result="ok", content="new content")
# ---------- 输出生成的 OpenAPI schema ----------
schema = app.openapi()
print(json.dumps(schema, indent=2, ensure_ascii=False))
app.openapi = custom_openapi # type: ignore[method-assign]
src/nyahome/router/admin_router.py
+1 -1
View File
@@ -19,7 +19,7 @@ from .response_model import ReturnDto
logger = logging.getLogger(__name__)
admin_router = APIRouter(tags=["admin"], prefix="/admin")
admin_router = APIRouter(tags=["Admin"], prefix="/admin")
class UserLogin(BaseModel):
webui/components.d.ts
Vendored
+2
View File
@@ -15,6 +15,7 @@ declare module 'vue' {
AiiModelAddModal: typeof import('./src/components/chatroom/AiiModelAddModal.vue')['default']
AiiProviderAddModal: typeof import('./src/components/chatroom/AiiProviderAddModal.vue')['default']
ChangeEmailModal: typeof import('./src/components/admin/ChangeEmailModal.vue')['default']
ChangePhoneModal: typeof import('./src/components/admin/ChangePhoneModal.vue')['default']
ChatControlPanel: typeof import('./src/components/chatroom/ChatControlPanel.vue')['default']
ChatMessage: typeof import('./src/components/chatroom/ChatMessage.vue')['default']
ChatPromptQuicker: typeof import('./src/components/chatroom/ChatPromptQuicker.vue')['default']
@@ -84,6 +85,7 @@ declare global {
const AiiModelAddModal: typeof import('./src/components/chatroom/AiiModelAddModal.vue')['default']
const AiiProviderAddModal: typeof import('./src/components/chatroom/AiiProviderAddModal.vue')['default']
const ChangeEmailModal: typeof import('./src/components/admin/ChangeEmailModal.vue')['default']
const ChangePhoneModal: typeof import('./src/components/admin/ChangePhoneModal.vue')['default']
const ChatControlPanel: typeof import('./src/components/chatroom/ChatControlPanel.vue')['default']
const ChatMessage: typeof import('./src/components/chatroom/ChatMessage.vue')['default']
const ChatPromptQuicker: typeof import('./src/components/chatroom/ChatPromptQuicker.vue')['default']
webui/src/assets/main.scss
+4
View File
@@ -6,6 +6,10 @@ body {
overflow: hidden;
}
* {
box-sizing: border-box;
}
div#app {
height: 100%;
overflow: hidden;
webui/src/pages/AdminPage.vue
+3 -1
View File
@@ -62,7 +62,9 @@ function handleMenuClick(key: string) {
onMounted(() => {
const key = ROUTER.currentRoute.value.fullPath.replace('/admin/', '')
if (key) {
if (key.endsWith('/admin')) {
selectOption.value = ''
} else if (key) {
selectOption.value = key
menu.value?.showOption(key)
} else {
webui/tsconfig.node.json
-3
View File
@@ -13,13 +13,10 @@
// Bundler mode provides a smoother developer experience.
"module": "preserve",
"moduleResolution": "bundler",
// Include Node.js types and avoid accidentally including other `@types/*` packages.
"types": ["node"],
// Disable emitting output during `vue-tsc --build`, which is used for type-checking only.
"noEmit": true,
// `vue-tsc --build` produces a .tsbuildinfo file for incremental type-checking.
// Specified here to keep it out of the root directory.
"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo"
webui/vite.config.ts
+11 -16
View File
@@ -4,15 +4,15 @@ import {defineConfig} from 'vite'
import vue from '@vitejs/plugin-vue'
import vueJsx from '@vitejs/plugin-vue-jsx'
import vueDevTools from 'vite-plugin-vue-devtools'
import {readFileSync} from "node:fs";
import {resolve} from "path";
import {readFileSync} from 'node:fs'
import {resolve} from 'path'
import AutoImport from 'unplugin-auto-import/vite'
import {NaiveUiResolver} from 'unplugin-vue-components/resolvers'
import Components from 'unplugin-vue-components/vite'
import {unheadVueComposablesImports} from "@unhead/vue";
import {unheadVueComposablesImports} from '@unhead/vue'
// 从 package.json 里搞到 WebUI 版本号
const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'));
const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'))
// https://vite.dev/config/
export default defineConfig({
@@ -24,22 +24,17 @@ export default defineConfig({
imports: [
'vue',
{
'naive-ui': [
'useDialog',
'useMessage',
'useNotification',
'useLoadingBar'
]
'naive-ui': ['useDialog', 'useMessage', 'useNotification', 'useLoadingBar'],
},
unheadVueComposablesImports,
]
],
}),
Components({
resolvers: [NaiveUiResolver()]
})
resolvers: [NaiveUiResolver()],
}),
],
define: {
__VERSION__: JSON.stringify(pkg.version)
__VERSION__: JSON.stringify(pkg.version),
},
build: {
rolldownOptions: {
@@ -47,11 +42,11 @@ export default defineConfig({
index: resolve(__dirname, 'index.html'),
},
},
outDir: "../src/nyahome/static"
outDir: '../src/nyahome/static',
},
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url))
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
server: {