修改blog文档顺序
This commit is contained in:
@@ -8,246 +8,6 @@ export default defineAppConfig({
|
||||
base: 'w-full h-full mx-auto px-2 sm:px-6 lg:px-8'
|
||||
}
|
||||
},
|
||||
uiPro: {
|
||||
modal: {
|
||||
slots: {
|
||||
overlay: 'fixed inset-0 bg-elevated/75',
|
||||
content: 'fixed bg-default divide-y divide-default flex flex-col focus:outline-none',
|
||||
header: 'flex items-center gap-1.5 p-4 sm:px-6 min-h-16',
|
||||
wrapper: '',
|
||||
body: 'flex-1 overflow-y-auto p-4 sm:p-6',
|
||||
footer: 'flex items-center gap-1.5 p-4 sm:px-6',
|
||||
title: 'text-highlighted font-semibold',
|
||||
description: 'mt-1 text-muted text-sm',
|
||||
close: 'absolute top-4 end-4'
|
||||
},
|
||||
variants: {
|
||||
fullscreen: {
|
||||
true: {
|
||||
content: 'inset-0'
|
||||
},
|
||||
false: {
|
||||
content: 'top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[calc(100vw-2rem)] max-w-lg max-h-[calc(100dvh-2rem)] sm:max-h-[calc(100dvh-4rem)] rounded-lg shadow-lg ring ring-default overflow-hidden'
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
footer: {
|
||||
slots: {
|
||||
root: 'border-t border-default',
|
||||
left: 'text-sm text-muted'
|
||||
}
|
||||
},
|
||||
pageCard: {
|
||||
slots: {
|
||||
root: 'relative flex rounded-lg',
|
||||
spotlight: 'absolute inset-0 rounded-[inherit] pointer-events-none bg-default/90',
|
||||
container: 'relative flex flex-col flex-1 lg:grid gap-x-8 gap-y-4 p-4 sm:p-6',
|
||||
wrapper: 'flex flex-col flex-1 items-start',
|
||||
header: 'mb-4',
|
||||
body: 'flex-1',
|
||||
footer: 'pt-4 mt-auto',
|
||||
leading: 'inline-flex items-center mb-2.5',
|
||||
leadingIcon: 'size-5 shrink-0 text-primary',
|
||||
title: 'text-base text-pretty font-semibold text-highlighted',
|
||||
description: 'text-[15px] text-pretty'
|
||||
},
|
||||
variants: {
|
||||
orientation: {
|
||||
horizontal: {
|
||||
container: 'lg:grid-cols-2 lg:items-center'
|
||||
},
|
||||
vertical: {
|
||||
container: ''
|
||||
}
|
||||
},
|
||||
reverse: {
|
||||
true: {
|
||||
wrapper: 'lg:order-last'
|
||||
}
|
||||
},
|
||||
variant: {
|
||||
solid: {
|
||||
root: 'bg-inverted text-inverted',
|
||||
title: 'text-inverted',
|
||||
description: 'text-dimmed'
|
||||
},
|
||||
outline: {
|
||||
root: 'bg-default ring ring-default',
|
||||
description: 'text-muted'
|
||||
},
|
||||
soft: {
|
||||
root: 'bg-elevated/50',
|
||||
description: 'text-toned'
|
||||
},
|
||||
subtle: {
|
||||
root: 'bg-elevated/50 ring ring-default',
|
||||
description: 'text-toned'
|
||||
},
|
||||
ghost: {
|
||||
description: 'text-muted'
|
||||
},
|
||||
naked: {
|
||||
container: 'p-0 sm:p-0',
|
||||
description: 'text-muted'
|
||||
}
|
||||
},
|
||||
to: {
|
||||
true: {
|
||||
root: [
|
||||
'transition'
|
||||
]
|
||||
}
|
||||
},
|
||||
title: {
|
||||
true: {
|
||||
description: 'mt-1'
|
||||
}
|
||||
},
|
||||
highlight: {
|
||||
true: {
|
||||
root: 'ring-2'
|
||||
}
|
||||
},
|
||||
highlightColor: {
|
||||
primary: '',
|
||||
secondary: '',
|
||||
success: '',
|
||||
info: '',
|
||||
warning: '',
|
||||
error: '',
|
||||
neutral: ''
|
||||
},
|
||||
spotlight: {
|
||||
true: {
|
||||
root: '[--spotlight-size:400px] before:absolute before:-inset-px before:pointer-events-none before:rounded-[inherit] before:bg-[radial-gradient(var(--spotlight-size)_var(--spotlight-size)_at_calc(var(--spotlight-x,0px))_calc(var(--spotlight-y,0px)),var(--spotlight-color),transparent_70%)]'
|
||||
}
|
||||
},
|
||||
spotlightColor: {
|
||||
primary: '',
|
||||
secondary: '',
|
||||
success: '',
|
||||
info: '',
|
||||
warning: '',
|
||||
error: '',
|
||||
neutral: ''
|
||||
}
|
||||
},
|
||||
compoundVariants: [
|
||||
{
|
||||
variant: 'solid',
|
||||
to: true,
|
||||
class: {
|
||||
root: 'hover:bg-inverted/90'
|
||||
}
|
||||
},
|
||||
{
|
||||
variant: 'outline',
|
||||
to: true,
|
||||
class: {
|
||||
root: 'hover:bg-elevated/50'
|
||||
}
|
||||
},
|
||||
{
|
||||
variant: 'soft',
|
||||
to: true,
|
||||
class: {
|
||||
root: 'hover:bg-elevated'
|
||||
}
|
||||
},
|
||||
{
|
||||
variant: 'subtle',
|
||||
to: true,
|
||||
class: {
|
||||
root: 'hover:bg-elevated'
|
||||
}
|
||||
},
|
||||
{
|
||||
variant: 'subtle',
|
||||
to: true,
|
||||
highlight: false,
|
||||
class: {
|
||||
root: 'hover:ring-accented'
|
||||
}
|
||||
},
|
||||
{
|
||||
variant: 'ghost',
|
||||
to: true,
|
||||
class: {
|
||||
root: 'hover:bg-elevated/50'
|
||||
}
|
||||
},
|
||||
{
|
||||
highlightColor: 'primary',
|
||||
highlight: true,
|
||||
class: {
|
||||
root: 'ring-primary'
|
||||
}
|
||||
},
|
||||
{
|
||||
highlightColor: 'neutral',
|
||||
highlight: true,
|
||||
class: {
|
||||
root: 'ring-inverted'
|
||||
}
|
||||
},
|
||||
{
|
||||
spotlightColor: 'primary',
|
||||
spotlight: true,
|
||||
class: {
|
||||
root: '[--spotlight-color:var(--ui-primary)]'
|
||||
}
|
||||
},
|
||||
{
|
||||
spotlightColor: 'secondary',
|
||||
spotlight: true,
|
||||
class: {
|
||||
root: '[--spotlight-color:var(--ui-secondary)]'
|
||||
}
|
||||
},
|
||||
{
|
||||
spotlightColor: 'success',
|
||||
spotlight: true,
|
||||
class: {
|
||||
root: '[--spotlight-color:var(--ui-success)]'
|
||||
}
|
||||
},
|
||||
{
|
||||
spotlightColor: 'info',
|
||||
spotlight: true,
|
||||
class: {
|
||||
root: '[--spotlight-color:var(--ui-info)]'
|
||||
}
|
||||
},
|
||||
{
|
||||
spotlightColor: 'warning',
|
||||
spotlight: true,
|
||||
class: {
|
||||
root: '[--spotlight-color:var(--ui-warning)]'
|
||||
}
|
||||
},
|
||||
{
|
||||
spotlightColor: 'error',
|
||||
spotlight: true,
|
||||
class: {
|
||||
root: '[--spotlight-color:var(--ui-error)]'
|
||||
}
|
||||
},
|
||||
{
|
||||
spotlightColor: 'neutral',
|
||||
spotlight: true,
|
||||
class: {
|
||||
root: '[--spotlight-color:var(--ui-bg-inverted)]'
|
||||
}
|
||||
}
|
||||
],
|
||||
defaultVariants: {
|
||||
variant: 'outline',
|
||||
highlightColor: 'primary',
|
||||
spotlightColor: 'primary'
|
||||
}
|
||||
}
|
||||
},
|
||||
seo: {
|
||||
siteName: 'Nuxt Docs Template'
|
||||
},
|
||||
|
||||
@@ -45,7 +45,7 @@ navigation:
|
||||
请一次性提供完整的HTML文件代码（包括HTML、CSS和JavaScript），代码需可直接保存为.html文件并在浏览器中运行。代码中需包含注释，体现逻辑清晰度和编程能力。
|
||||
|
||||
GROK3:
|
||||
```
|
||||
```html[GROK3.html]
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="zh-CN">
|
||||
@@ -464,7 +464,7 @@ GROK3:
|
||||
```
|
||||
|
||||
R1:
|
||||
```
|
||||
```html[R1.html]
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="zh-CN">
|
||||
@@ -1,238 +1,190 @@
|
||||
---
|
||||
title: 记录AI
|
||||
description: 学习 AI 相关知识
|
||||
date: 2025-08-07
|
||||
title: Coolify
|
||||
description: Coolify是什么？
|
||||
date: 2025-07-14
|
||||
img: https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250628122847084.png
|
||||
navigation:
|
||||
icon: lucide-house
|
||||
icon: simple-icons:chai
|
||||
---
|
||||
# 概述
|
||||
这是一份提供给AI大模型的Python代码规范与编程标准，可以有效提高Cursor等大模型对Python项目的编写能力。
|
||||
|
||||
## 博客
|
||||
---
|
||||
description: Python开发综合指南，涵盖代码组织、性能、安全性、测试等内容。这些规则旨在促进可维护、高效且安全的Python代码库。
|
||||
globs: *.py
|
||||
---
|
||||
# Python最佳实践与编码规范
|
||||
|
||||
使用过市面上的很多文档系统，但是或多或少都有一些自己不满意的功能.
|
||||
于是自己动手，丰衣足食.
|
||||
同时在 Markdown 语法的基础上增加了许多**魔法(自定义组件)**,比如:
|
||||
本文档概述了Python开发的综合最佳实践和编码标准，旨在促进编写干净、高效、可维护和安全的代码。
|
||||
|
||||
## 1. 代码组织与结构
|
||||
|
||||
::code-group
|
||||
```mdc [index.md]
|
||||
在 Markdown 中使用::card 标签,即可创建一个卡片,卡片里可以放置任何内容。比如以下内容:
|
||||
::card
|
||||
这里是卡片里的内容
|
||||
::
|
||||
```
|
||||
### 1.1 目录结构最佳实践
|
||||
|
||||
```html [Card.vue]
|
||||
<!-- Card组件: components/content/Card.vue -->
|
||||
<template>
|
||||
<div class="p-2 border bg-white dark:bg-black dark:border-gray-700 rounded">
|
||||
<slot />
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
:::code-preview{icon="i-lucide-eye" label="Preview"}
|
||||
::::example-card
|
||||
这里是卡片里的内容
|
||||
::::
|
||||
:::
|
||||
* **扁平结构优于嵌套（但不绝对）。** 从简单结构开始，按需重构
|
||||
* **包与模块：** 使用包（包含`__init__.py`的目录）对模块进行逻辑分组
|
||||
* **src布局：** 考虑使用`src`目录分离应用代码和项目级文件（setup.py、requirements.txt等），避免导入冲突并明确项目边界
|
||||
* **典型项目结构：**
|
||||
|
||||
::
|
||||
project_name/
|
||||
├── src/
|
||||
│ ├── package_name/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── module1.py
|
||||
│ │ ├── module2.py
|
||||
│ ├── main.py # 入口文件
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ ├── test_module1.py
|
||||
│ ├── test_module2.py
|
||||
├── docs/
|
||||
│ ├── conf.py
|
||||
│ ├── index.rst
|
||||
├── .gitignore
|
||||
├── pyproject.toml 或 setup.py
|
||||
├── README.md
|
||||
├── requirements.txt 或 requirements-dev.txt
|
||||
|
||||
:::UPageCard{icon="lucide-code" title="代码组" description="这个组件使用 自定义的 Markdown 语法,从 Markdown 中提取代码块,并展示在页面上 (而其自身亦是一个卡片组)"}
|
||||
### 1.2 文件命名规范
|
||||
|
||||
::code-tree{defaultValue="nuxt.config.ts"}
|
||||
* **模块：** 小写字母，使用下划线增强可读性（如`my_module.py`）
|
||||
* **包：** 全小写（如`my_package`），非必要不使用下划线
|
||||
* **测试文件：** 以`test_`开头（如`test_my_module.py`）
|
||||
|
||||
```css [app/assets/main.css]
|
||||
@import "tailwindcss" theme(static);
|
||||
@import "@nuxt/ui-pro";
|
||||
```
|
||||
### 1.3 模块组织最佳实践
|
||||
|
||||
```ts [app/app.config.ts]
|
||||
export default defineAppConfig({
|
||||
ui: {
|
||||
colors: {
|
||||
primary: 'sky',
|
||||
colors: 'slate'
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
* **单一职责原则：** 每个模块应有明确定义的用途
|
||||
* **导入规范：**
|
||||
* 顺序：标准库→第三方库→本地模块
|
||||
* 优先使用绝对导入（如`from my_package.module1 import function1`）
|
||||
* 在复杂包结构中需明确相对导入时使用显式相对导入（`from . import sibling_module`）
|
||||
* **常量：** 使用全大写定义模块级常量（如`MAX_ITERATIONS = 100`）
|
||||
* **双下划线名称：** `__all__`、`__version__`等应放在模块文档字符串之后、所有导入之前（`from __future__`除外）。使用`__all__`显式声明公共API
|
||||
|
||||
```vue [app/app.vue]
|
||||
<template>
|
||||
<UApp>
|
||||
<NuxtPage />
|
||||
</UApp>
|
||||
</template>
|
||||
```
|
||||
### 1.4 组件架构建议
|
||||
|
||||
```json [package.json]
|
||||
{
|
||||
"name": "nuxt-app",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"build": "nuxt build",
|
||||
"dev": "nuxt dev",
|
||||
"generate": "nuxt generate",
|
||||
"preview": "nuxt preview",
|
||||
"postinstall": "nuxt prepare",
|
||||
"typecheck": "nuxt typecheck"
|
||||
},
|
||||
"dependencies": {
|
||||
"@iconify-json/lucide": "^1.2.18",
|
||||
"@nuxt/ui-pro": "3.0.0-alpha.10",
|
||||
"nuxt": "^3.15.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"typescript": "^5.7.2",
|
||||
"vue-tsc": "^2.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
* **分层架构：** 适用于大型应用，将关注点分离为表现层、业务逻辑层和数据访问层
|
||||
* **微服务：** 超大型系统可拆分为小型独立服务
|
||||
* **六边形/整洁架构：** 强调业务逻辑与数据库/框架等外部依赖的解耦
|
||||
* **依赖注入：** 提高可测试性并降低耦合度
|
||||
|
||||
```json [tsconfig.json]
|
||||
{
|
||||
"extends": "./.nuxt/tsconfig.json"
|
||||
}
|
||||
```
|
||||
### 1.5 代码分割策略
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxt/ui-pro'],
|
||||
* **按功能拆分：** 基于不同功能划分模块（如用户管理、数据处理）
|
||||
* **按层级拆分：** 分离表现层、业务逻辑层和数据访问代码
|
||||
* **懒加载：** 使用`importlib.import_module()`实现按需加载，优化启动时间
|
||||
* **条件导入：** 根据特定条件导入模块
|
||||
|
||||
future: {
|
||||
compatibilityVersion: 4
|
||||
},
|
||||
## 2. 常见模式与反模式
|
||||
|
||||
css: ['~/assets/main.css']
|
||||
});
|
||||
```
|
||||
### 2.1 设计模式
|
||||
|
||||
````md [README.md]
|
||||
# Nuxt 3 Minimal Starter
|
||||
* **单例模式：** 限制类只能实例化一个对象
|
||||
* **工厂模式：** 创建对象时无需指定具体类
|
||||
* **观察者模式：** 建立对象间一对多依赖关系
|
||||
* **策略模式：** 定义算法族并使其可互换
|
||||
* **装饰器模式：** 动态扩展对象功能
|
||||
* **上下文管理器：** 确保资源正确清理（如自动关闭文件）
|
||||
|
||||
Look at the [Nuxt 3 documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
|
||||
### 2.2 常见任务的推荐方案
|
||||
|
||||
## Setup
|
||||
* **数据验证：** 使用`pydantic`或`marshmallow`等库
|
||||
* **配置管理：** 使用`python-decouple`、`dynaconf`或标准库的`configparser`
|
||||
* **日志记录：** 使用`logging`模块实现结构化日志
|
||||
* **命令行接口：** 使用`argparse`、`click`或`typer`
|
||||
* **异步编程：** 使用`asyncio`处理I/O密集型任务
|
||||
|
||||
Make sure to install the dependencies:
|
||||
### 2.3 反模式与代码异味
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm install
|
||||
* **上帝类：** 承担过多职责的类，应拆分为专注单一功能的小类
|
||||
* **霰弹式变更：** 需在多处做小修改，表明内聚性不足
|
||||
* **面条代码：** 结构混乱难以追踪，应重构为定义明确的函数/类
|
||||
* **重复代码：** 提取公共代码为可复用函数/类（遵循DRY原则）
|
||||
* **魔法数值/字符串：** 使用命名常量替代硬编码值
|
||||
* **过早优化：** 避免在没有性能瓶颈分析前提下的优化
|
||||
|
||||
# pnpm
|
||||
pnpm install
|
||||
### 2.4 状态管理最佳实践
|
||||
|
||||
# yarn
|
||||
yarn install
|
||||
* **无状态函数：** 尽可能使用无状态函数
|
||||
* **不可变数据：** 使用不可变数据结构防止意外修改
|
||||
* **显式状态：** 使用类或数据结构明确管理状态，避免全局变量
|
||||
* **上下文变量：** Python 3.7+可使用`contextvars`管理异步应用中的请求级状态
|
||||
|
||||
# bun
|
||||
bun install
|
||||
```
|
||||
### 2.5 错误处理模式
|
||||
|
||||
## Development Server
|
||||
* **捕获特定异常：** 避免笼统捕获`Exception`或`BaseException`
|
||||
* **资源清理：** 使用`finally`确保清理代码必执行
|
||||
* **异常日志：** 记录完整堆栈信息
|
||||
* **异常消息：** 抛出包含明确错误信息的异常
|
||||
* **避免异常控制流：** 异常应用于处理意外情况而非常规流程
|
||||
|
||||
Start the development server on `http://localhost:3000`:
|
||||
## 3. 性能优化
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm run dev
|
||||
### 3.1 优化技术
|
||||
|
||||
# pnpm
|
||||
pnpm run dev
|
||||
* **性能分析：** 使用`cProfile`定位瓶颈
|
||||
* **高效数据结构：** 根据场景选择（如`set`用于成员测试、`dict`用于查找）
|
||||
* **列表推导式与生成器：** 编写简洁高效的代码
|
||||
* **NumPy向量化：** 对数值计算使用向量化操作
|
||||
* **即时编译：** 性能关键代码考虑使用Numba等JIT编译器
|
||||
* **字符串拼接：** 使用`''.join(iterable)`高效拼接字符串
|
||||
|
||||
# yarn
|
||||
yarn dev
|
||||
### 3.2 内存管理
|
||||
|
||||
# bun
|
||||
bun run dev
|
||||
```
|
||||
* **内存分析：** 使用`memory_profiler`定位内存泄漏
|
||||
* **`__slots__`：** 减少类实例的内存占用
|
||||
* **生成器：** 处理大数据集时避免全部加载到内存
|
||||
|
||||
## Production
|
||||
## 4. 安全性最佳实践
|
||||
|
||||
Build the application for production:
|
||||
### 4.1 常见漏洞防范
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm run build
|
||||
* **SQL注入：** 使用参数化查询或ORM
|
||||
* **XSS攻击：** 对用户输入消毒并转义输出
|
||||
* **CSRF防护：** 使用CSRF令牌
|
||||
* **依赖漏洞：** 定期审计和更新依赖项
|
||||
* **硬编码密钥：** 禁止在代码中硬编码密码/API密钥，使用环境变量管理
|
||||
|
||||
# pnpm
|
||||
pnpm run build
|
||||
### 4.2 API安全通信
|
||||
|
||||
# yarn
|
||||
yarn build
|
||||
* **强制HTTPS：** 所有API通信必须加密
|
||||
* **速率限制：** 防止接口滥用
|
||||
* **输入验证：** 处理前验证所有API请求
|
||||
|
||||
# bun
|
||||
bun run build
|
||||
```
|
||||
## 5. 测试策略
|
||||
|
||||
Locally preview production build:
|
||||
### 5.1 单元测试要点
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm run preview
|
||||
* **测试粒度：** 隔离测试单个函数/类/模块
|
||||
* **边界条件：** 特别测试边界情况和异常场景
|
||||
* **测试覆盖率：** 追求高覆盖率但避免教条化
|
||||
|
||||
# pnpm
|
||||
pnpm run preview
|
||||
### 5.2 集成测试建议
|
||||
|
||||
# yarn
|
||||
yarn preview
|
||||
* **聚焦关键流程：** 关注核心用户场景
|
||||
* **模拟外部服务：** 使用mock替代真实外部依赖
|
||||
|
||||
# bun
|
||||
bun run preview
|
||||
```
|
||||
## 6. 常见陷阱
|
||||
|
||||
Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
|
||||
````
|
||||
### 6.1 高频错误
|
||||
|
||||
::
|
||||
:::
|
||||
* **可变默认参数：** 函数定义中避免使用可变对象作为默认值
|
||||
* **变量作用域：** 注意嵌套函数中的变量作用域
|
||||
* **忽略异常：** 禁止直接忽略未处理的异常
|
||||
* **虚拟环境：** 必须使用虚拟环境管理项目依赖
|
||||
|
||||
::code-group
|
||||
```md [搜索.md]
|
||||
#### 此组件打开一个模态搜索框,进行搜索
|
||||
::::example-fulltext-content-search
|
||||
::::
|
||||
## 7. 工具与环境
|
||||
|
||||
#### 此组件建立一个mini搜索框,进行搜索
|
||||
::::example-fulltext-mini-search
|
||||
::::
|
||||
```
|
||||
### 7.1 推荐工具链
|
||||
|
||||
:::code-preview{label="预览模态组件" icon="i-lucide-eye"}
|
||||
::::example-fulltext-content-search
|
||||
::::
|
||||
:::
|
||||
:::code-preview{label="预览搜索框组件" icon="i-lucide-eye"}
|
||||
::::example-fulltext-mini-search
|
||||
::::
|
||||
:::
|
||||
|
||||
::
|
||||
* **IDE：** PyCharm、VS Code（搭配Python插件）
|
||||
* **包管理：** `pip`、`poetry`
|
||||
* **格式化：** `black`、`autopep8`
|
||||
* **静态检查：** `mypy`、`pylint`
|
||||
|
||||
### 7.2 CI/CD集成
|
||||
|
||||
::tip{icon="lucide-info" color="primary" class="text-black dark:text-white"}
|
||||
阅读更多关于 [`自定义组件`](/简单文档/components/api) 的内容.
|
||||
::
|
||||
* **自动化测试：** 每次提交自动运行测试套件
|
||||
* **代码质量门禁：** 集成静态分析工具到流水线
|
||||
|
||||
|
||||
## 特性
|
||||
|
||||
- 基于 Nuxt 4 , Content v3 , Nuxt UI Pro 构建的文档系统。
|
||||
- 完美支持 Markdown 和 相关扩展。
|
||||
- 和 Vue 组件高度集成。
|
||||
- 支持搜索,由Content v3 赋能。
|
||||
- 支持多主题,使用Nuxt UI Pro。
|
||||
- 开源且免费。
|
||||
- 支持移动端。
|
||||
|
||||
## 致谢
|
||||
|
||||
- Nuxt Content：为 Vue 开发者简化内容管理。
|
||||
- Nuxt UI Pro ：文档系统 UI 组件。
|
||||
- Docus：获取灵感及一些文档组件源代码。
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
遵循这些规范和最佳实践，开发者能够构建出更健壮、可维护且安全的Python应用。
|
||||
@@ -1,238 +1,190 @@
|
||||
---
|
||||
title: 记录生活
|
||||
description: 记录生活点点滴滴
|
||||
date: 2025-08-07
|
||||
title: Coolify
|
||||
description: Coolify是什么？
|
||||
date: 2025-07-14
|
||||
img: https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250628122847084.png
|
||||
navigation:
|
||||
icon: lucide-house
|
||||
icon: simple-icons:chai
|
||||
---
|
||||
# 概述
|
||||
这是一份提供给AI大模型的Python代码规范与编程标准，可以有效提高Cursor等大模型对Python项目的编写能力。
|
||||
|
||||
## 博客
|
||||
---
|
||||
description: Python开发综合指南，涵盖代码组织、性能、安全性、测试等内容。这些规则旨在促进可维护、高效且安全的Python代码库。
|
||||
globs: *.py
|
||||
---
|
||||
# Python最佳实践与编码规范
|
||||
|
||||
使用过市面上的很多文档系统，但是或多或少都有一些自己不满意的功能.
|
||||
于是自己动手，丰衣足食.
|
||||
同时在 Markdown 语法的基础上增加了许多**魔法(自定义组件)**,比如:
|
||||
本文档概述了Python开发的综合最佳实践和编码标准，旨在促进编写干净、高效、可维护和安全的代码。
|
||||
|
||||
## 1. 代码组织与结构
|
||||
|
||||
::code-group
|
||||
```mdc [index.md]
|
||||
在 Markdown 中使用::card 标签,即可创建一个卡片,卡片里可以放置任何内容。比如以下内容:
|
||||
::card
|
||||
这里是卡片里的内容
|
||||
::
|
||||
```
|
||||
### 1.1 目录结构最佳实践
|
||||
|
||||
```html [Card.vue]
|
||||
<!-- Card组件: components/content/Card.vue -->
|
||||
<template>
|
||||
<div class="p-2 border bg-white dark:bg-black dark:border-gray-700 rounded">
|
||||
<slot />
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
:::code-preview{icon="i-lucide-eye" label="Preview"}
|
||||
::::example-card
|
||||
这里是卡片里的内容
|
||||
::::
|
||||
:::
|
||||
* **扁平结构优于嵌套（但不绝对）。** 从简单结构开始，按需重构
|
||||
* **包与模块：** 使用包（包含`__init__.py`的目录）对模块进行逻辑分组
|
||||
* **src布局：** 考虑使用`src`目录分离应用代码和项目级文件（setup.py、requirements.txt等），避免导入冲突并明确项目边界
|
||||
* **典型项目结构：**
|
||||
|
||||
::
|
||||
project_name/
|
||||
├── src/
|
||||
│ ├── package_name/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── module1.py
|
||||
│ │ ├── module2.py
|
||||
│ ├── main.py # 入口文件
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ ├── test_module1.py
|
||||
│ ├── test_module2.py
|
||||
├── docs/
|
||||
│ ├── conf.py
|
||||
│ ├── index.rst
|
||||
├── .gitignore
|
||||
├── pyproject.toml 或 setup.py
|
||||
├── README.md
|
||||
├── requirements.txt 或 requirements-dev.txt
|
||||
|
||||
:::UPageCard{icon="lucide-code" title="代码组" description="这个组件使用 自定义的 Markdown 语法,从 Markdown 中提取代码块,并展示在页面上 (而其自身亦是一个卡片组)"}
|
||||
### 1.2 文件命名规范
|
||||
|
||||
::code-tree{defaultValue="nuxt.config.ts"}
|
||||
* **模块：** 小写字母，使用下划线增强可读性（如`my_module.py`）
|
||||
* **包：** 全小写（如`my_package`），非必要不使用下划线
|
||||
* **测试文件：** 以`test_`开头（如`test_my_module.py`）
|
||||
|
||||
```css [app/assets/main.css]
|
||||
@import "tailwindcss" theme(static);
|
||||
@import "@nuxt/ui-pro";
|
||||
```
|
||||
### 1.3 模块组织最佳实践
|
||||
|
||||
```ts [app/app.config.ts]
|
||||
export default defineAppConfig({
|
||||
ui: {
|
||||
colors: {
|
||||
primary: 'sky',
|
||||
colors: 'slate'
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
* **单一职责原则：** 每个模块应有明确定义的用途
|
||||
* **导入规范：**
|
||||
* 顺序：标准库→第三方库→本地模块
|
||||
* 优先使用绝对导入（如`from my_package.module1 import function1`）
|
||||
* 在复杂包结构中需明确相对导入时使用显式相对导入（`from . import sibling_module`）
|
||||
* **常量：** 使用全大写定义模块级常量（如`MAX_ITERATIONS = 100`）
|
||||
* **双下划线名称：** `__all__`、`__version__`等应放在模块文档字符串之后、所有导入之前（`from __future__`除外）。使用`__all__`显式声明公共API
|
||||
|
||||
```vue [app/app.vue]
|
||||
<template>
|
||||
<UApp>
|
||||
<NuxtPage />
|
||||
</UApp>
|
||||
</template>
|
||||
```
|
||||
### 1.4 组件架构建议
|
||||
|
||||
```json [package.json]
|
||||
{
|
||||
"name": "nuxt-app",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"build": "nuxt build",
|
||||
"dev": "nuxt dev",
|
||||
"generate": "nuxt generate",
|
||||
"preview": "nuxt preview",
|
||||
"postinstall": "nuxt prepare",
|
||||
"typecheck": "nuxt typecheck"
|
||||
},
|
||||
"dependencies": {
|
||||
"@iconify-json/lucide": "^1.2.18",
|
||||
"@nuxt/ui-pro": "3.0.0-alpha.10",
|
||||
"nuxt": "^3.15.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"typescript": "^5.7.2",
|
||||
"vue-tsc": "^2.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
* **分层架构：** 适用于大型应用，将关注点分离为表现层、业务逻辑层和数据访问层
|
||||
* **微服务：** 超大型系统可拆分为小型独立服务
|
||||
* **六边形/整洁架构：** 强调业务逻辑与数据库/框架等外部依赖的解耦
|
||||
* **依赖注入：** 提高可测试性并降低耦合度
|
||||
|
||||
```json [tsconfig.json]
|
||||
{
|
||||
"extends": "./.nuxt/tsconfig.json"
|
||||
}
|
||||
```
|
||||
### 1.5 代码分割策略
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxt/ui-pro'],
|
||||
* **按功能拆分：** 基于不同功能划分模块（如用户管理、数据处理）
|
||||
* **按层级拆分：** 分离表现层、业务逻辑层和数据访问代码
|
||||
* **懒加载：** 使用`importlib.import_module()`实现按需加载，优化启动时间
|
||||
* **条件导入：** 根据特定条件导入模块
|
||||
|
||||
future: {
|
||||
compatibilityVersion: 4
|
||||
},
|
||||
## 2. 常见模式与反模式
|
||||
|
||||
css: ['~/assets/main.css']
|
||||
});
|
||||
```
|
||||
### 2.1 设计模式
|
||||
|
||||
````md [README.md]
|
||||
# Nuxt 3 Minimal Starter
|
||||
* **单例模式：** 限制类只能实例化一个对象
|
||||
* **工厂模式：** 创建对象时无需指定具体类
|
||||
* **观察者模式：** 建立对象间一对多依赖关系
|
||||
* **策略模式：** 定义算法族并使其可互换
|
||||
* **装饰器模式：** 动态扩展对象功能
|
||||
* **上下文管理器：** 确保资源正确清理（如自动关闭文件）
|
||||
|
||||
Look at the [Nuxt 3 documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
|
||||
### 2.2 常见任务的推荐方案
|
||||
|
||||
## Setup
|
||||
* **数据验证：** 使用`pydantic`或`marshmallow`等库
|
||||
* **配置管理：** 使用`python-decouple`、`dynaconf`或标准库的`configparser`
|
||||
* **日志记录：** 使用`logging`模块实现结构化日志
|
||||
* **命令行接口：** 使用`argparse`、`click`或`typer`
|
||||
* **异步编程：** 使用`asyncio`处理I/O密集型任务
|
||||
|
||||
Make sure to install the dependencies:
|
||||
### 2.3 反模式与代码异味
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm install
|
||||
* **上帝类：** 承担过多职责的类，应拆分为专注单一功能的小类
|
||||
* **霰弹式变更：** 需在多处做小修改，表明内聚性不足
|
||||
* **面条代码：** 结构混乱难以追踪，应重构为定义明确的函数/类
|
||||
* **重复代码：** 提取公共代码为可复用函数/类（遵循DRY原则）
|
||||
* **魔法数值/字符串：** 使用命名常量替代硬编码值
|
||||
* **过早优化：** 避免在没有性能瓶颈分析前提下的优化
|
||||
|
||||
# pnpm
|
||||
pnpm install
|
||||
### 2.4 状态管理最佳实践
|
||||
|
||||
# yarn
|
||||
yarn install
|
||||
* **无状态函数：** 尽可能使用无状态函数
|
||||
* **不可变数据：** 使用不可变数据结构防止意外修改
|
||||
* **显式状态：** 使用类或数据结构明确管理状态，避免全局变量
|
||||
* **上下文变量：** Python 3.7+可使用`contextvars`管理异步应用中的请求级状态
|
||||
|
||||
# bun
|
||||
bun install
|
||||
```
|
||||
### 2.5 错误处理模式
|
||||
|
||||
## Development Server
|
||||
* **捕获特定异常：** 避免笼统捕获`Exception`或`BaseException`
|
||||
* **资源清理：** 使用`finally`确保清理代码必执行
|
||||
* **异常日志：** 记录完整堆栈信息
|
||||
* **异常消息：** 抛出包含明确错误信息的异常
|
||||
* **避免异常控制流：** 异常应用于处理意外情况而非常规流程
|
||||
|
||||
Start the development server on `http://localhost:3000`:
|
||||
## 3. 性能优化
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm run dev
|
||||
### 3.1 优化技术
|
||||
|
||||
# pnpm
|
||||
pnpm run dev
|
||||
* **性能分析：** 使用`cProfile`定位瓶颈
|
||||
* **高效数据结构：** 根据场景选择（如`set`用于成员测试、`dict`用于查找）
|
||||
* **列表推导式与生成器：** 编写简洁高效的代码
|
||||
* **NumPy向量化：** 对数值计算使用向量化操作
|
||||
* **即时编译：** 性能关键代码考虑使用Numba等JIT编译器
|
||||
* **字符串拼接：** 使用`''.join(iterable)`高效拼接字符串
|
||||
|
||||
# yarn
|
||||
yarn dev
|
||||
### 3.2 内存管理
|
||||
|
||||
# bun
|
||||
bun run dev
|
||||
```
|
||||
* **内存分析：** 使用`memory_profiler`定位内存泄漏
|
||||
* **`__slots__`：** 减少类实例的内存占用
|
||||
* **生成器：** 处理大数据集时避免全部加载到内存
|
||||
|
||||
## Production
|
||||
## 4. 安全性最佳实践
|
||||
|
||||
Build the application for production:
|
||||
### 4.1 常见漏洞防范
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm run build
|
||||
* **SQL注入：** 使用参数化查询或ORM
|
||||
* **XSS攻击：** 对用户输入消毒并转义输出
|
||||
* **CSRF防护：** 使用CSRF令牌
|
||||
* **依赖漏洞：** 定期审计和更新依赖项
|
||||
* **硬编码密钥：** 禁止在代码中硬编码密码/API密钥，使用环境变量管理
|
||||
|
||||
# pnpm
|
||||
pnpm run build
|
||||
### 4.2 API安全通信
|
||||
|
||||
# yarn
|
||||
yarn build
|
||||
* **强制HTTPS：** 所有API通信必须加密
|
||||
* **速率限制：** 防止接口滥用
|
||||
* **输入验证：** 处理前验证所有API请求
|
||||
|
||||
# bun
|
||||
bun run build
|
||||
```
|
||||
## 5. 测试策略
|
||||
|
||||
Locally preview production build:
|
||||
### 5.1 单元测试要点
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm run preview
|
||||
* **测试粒度：** 隔离测试单个函数/类/模块
|
||||
* **边界条件：** 特别测试边界情况和异常场景
|
||||
* **测试覆盖率：** 追求高覆盖率但避免教条化
|
||||
|
||||
# pnpm
|
||||
pnpm run preview
|
||||
### 5.2 集成测试建议
|
||||
|
||||
# yarn
|
||||
yarn preview
|
||||
* **聚焦关键流程：** 关注核心用户场景
|
||||
* **模拟外部服务：** 使用mock替代真实外部依赖
|
||||
|
||||
# bun
|
||||
bun run preview
|
||||
```
|
||||
## 6. 常见陷阱
|
||||
|
||||
Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
|
||||
````
|
||||
### 6.1 高频错误
|
||||
|
||||
::
|
||||
:::
|
||||
* **可变默认参数：** 函数定义中避免使用可变对象作为默认值
|
||||
* **变量作用域：** 注意嵌套函数中的变量作用域
|
||||
* **忽略异常：** 禁止直接忽略未处理的异常
|
||||
* **虚拟环境：** 必须使用虚拟环境管理项目依赖
|
||||
|
||||
::code-group
|
||||
```md [搜索.md]
|
||||
#### 此组件打开一个模态搜索框,进行搜索
|
||||
::::example-fulltext-content-search
|
||||
::::
|
||||
## 7. 工具与环境
|
||||
|
||||
#### 此组件建立一个mini搜索框,进行搜索
|
||||
::::example-fulltext-mini-search
|
||||
::::
|
||||
```
|
||||
### 7.1 推荐工具链
|
||||
|
||||
:::code-preview{label="预览模态组件" icon="i-lucide-eye"}
|
||||
::::example-fulltext-content-search
|
||||
::::
|
||||
:::
|
||||
:::code-preview{label="预览搜索框组件" icon="i-lucide-eye"}
|
||||
::::example-fulltext-mini-search
|
||||
::::
|
||||
:::
|
||||
|
||||
::
|
||||
* **IDE：** PyCharm、VS Code（搭配Python插件）
|
||||
* **包管理：** `pip`、`poetry`
|
||||
* **格式化：** `black`、`autopep8`
|
||||
* **静态检查：** `mypy`、`pylint`
|
||||
|
||||
### 7.2 CI/CD集成
|
||||
|
||||
::tip{icon="lucide-info" color="primary" class="text-black dark:text-white"}
|
||||
阅读更多关于 [`自定义组件`](/docs/简单文档/components/api) 的内容.
|
||||
::
|
||||
* **自动化测试：** 每次提交自动运行测试套件
|
||||
* **代码质量门禁：** 集成静态分析工具到流水线
|
||||
|
||||
|
||||
## 特性
|
||||
|
||||
- 基于 Nuxt 4 , Content v3 , Nuxt UI Pro 构建的文档系统。
|
||||
- 完美支持 Markdown 和 相关扩展。
|
||||
- 和 Vue 组件高度集成。
|
||||
- 支持搜索,由Content v3 赋能。
|
||||
- 支持多主题,使用Nuxt UI Pro。
|
||||
- 开源且免费。
|
||||
- 支持移动端。
|
||||
|
||||
## 致谢
|
||||
|
||||
- Nuxt Content：为 Vue 开发者简化内容管理。
|
||||
- Nuxt UI Pro ：文档系统 UI 组件。
|
||||
- Docus：获取灵感及一些文档组件源代码。
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
遵循这些规范和最佳实践，开发者能够构建出更健壮、可维护且安全的Python应用。
|
||||
Reference in New Issue
Block a user