修改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'
|
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: {
|
seo: {
|
||||||
siteName: 'Nuxt Docs Template'
|
siteName: 'Nuxt Docs Template'
|
||||||
},
|
},
|
||||||
|
|||||||
@@ -45,7 +45,7 @@ navigation:
|
|||||||
请一次性提供完整的HTML文件代码（包括HTML、CSS和JavaScript），代码需可直接保存为.html文件并在浏览器中运行。代码中需包含注释，体现逻辑清晰度和编程能力。
|
请一次性提供完整的HTML文件代码（包括HTML、CSS和JavaScript），代码需可直接保存为.html文件并在浏览器中运行。代码中需包含注释，体现逻辑清晰度和编程能力。
|
||||||
|
|
||||||
GROK3:
|
GROK3:
|
||||||
```
|
```html[GROK3.html]
|
||||||
<!DOCTYPE html>
|
<!DOCTYPE html>
|
||||||
|
|
||||||
<html lang="zh-CN">
|
<html lang="zh-CN">
|
||||||
@@ -464,7 +464,7 @@ GROK3:
|
|||||||
```
|
```
|
||||||
|
|
||||||
R1:
|
R1:
|
||||||
```
|
```html[R1.html]
|
||||||
<!DOCTYPE html>
|
<!DOCTYPE html>
|
||||||
|
|
||||||
<html lang="zh-CN">
|
<html lang="zh-CN">
|
||||||
@@ -1,238 +1,190 @@
|
|||||||
---
|
---
|
||||||
title: 记录AI
|
title: Coolify
|
||||||
description: 学习 AI 相关知识
|
description: Coolify是什么？
|
||||||
date: 2025-08-07
|
date: 2025-07-14
|
||||||
|
img: https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250628122847084.png
|
||||||
navigation:
|
navigation:
|
||||||
icon: lucide-house
|
icon: simple-icons:chai
|
||||||
---
|
---
|
||||||
|
# 概述
|
||||||
|
这是一份提供给AI大模型的Python代码规范与编程标准，可以有效提高Cursor等大模型对Python项目的编写能力。
|
||||||
|
|
||||||
## 博客
|
---
|
||||||
|
description: Python开发综合指南，涵盖代码组织、性能、安全性、测试等内容。这些规则旨在促进可维护、高效且安全的Python代码库。
|
||||||
|
globs: *.py
|
||||||
|
---
|
||||||
|
# Python最佳实践与编码规范
|
||||||
|
|
||||||
使用过市面上的很多文档系统，但是或多或少都有一些自己不满意的功能.
|
本文档概述了Python开发的综合最佳实践和编码标准，旨在促进编写干净、高效、可维护和安全的代码。
|
||||||
于是自己动手，丰衣足食.
|
|
||||||
同时在 Markdown 语法的基础上增加了许多**魔法(自定义组件)**,比如:
|
|
||||||
|
|
||||||
|
## 1. 代码组织与结构
|
||||||
|
|
||||||
::code-group
|
### 1.1 目录结构最佳实践
|
||||||
```mdc [index.md]
|
|
||||||
在 Markdown 中使用::card 标签,即可创建一个卡片,卡片里可以放置任何内容。比如以下内容:
|
|
||||||
::card
|
|
||||||
这里是卡片里的内容
|
|
||||||
::
|
|
||||||
```
|
|
||||||
|
|
||||||
```html [Card.vue]
|
* **扁平结构优于嵌套（但不绝对）。** 从简单结构开始，按需重构
|
||||||
<!-- Card组件: components/content/Card.vue -->
|
* **包与模块：** 使用包（包含`__init__.py`的目录）对模块进行逻辑分组
|
||||||
<template>
|
* **src布局：** 考虑使用`src`目录分离应用代码和项目级文件（setup.py、requirements.txt等），避免导入冲突并明确项目边界
|
||||||
<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
|
|
||||||
这里是卡片里的内容
|
|
||||||
::::
|
|
||||||
:::
|
|
||||||
|
|
||||||
::
|
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]
|
### 1.3 模块组织最佳实践
|
||||||
@import "tailwindcss" theme(static);
|
|
||||||
@import "@nuxt/ui-pro";
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts [app/app.config.ts]
|
* **单一职责原则：** 每个模块应有明确定义的用途
|
||||||
export default defineAppConfig({
|
* **导入规范：**
|
||||||
ui: {
|
* 顺序：标准库→第三方库→本地模块
|
||||||
colors: {
|
* 优先使用绝对导入（如`from my_package.module1 import function1`）
|
||||||
primary: 'sky',
|
* 在复杂包结构中需明确相对导入时使用显式相对导入（`from . import sibling_module`）
|
||||||
colors: 'slate'
|
* **常量：** 使用全大写定义模块级常量（如`MAX_ITERATIONS = 100`）
|
||||||
}
|
* **双下划线名称：** `__all__`、`__version__`等应放在模块文档字符串之后、所有导入之前（`from __future__`除外）。使用`__all__`显式声明公共API
|
||||||
}
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
```vue [app/app.vue]
|
### 1.4 组件架构建议
|
||||||
<template>
|
|
||||||
<UApp>
|
|
||||||
<NuxtPage />
|
|
||||||
</UApp>
|
|
||||||
</template>
|
|
||||||
```
|
|
||||||
|
|
||||||
```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]
|
### 1.5 代码分割策略
|
||||||
{
|
|
||||||
"extends": "./.nuxt/tsconfig.json"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts [nuxt.config.ts]
|
* **按功能拆分：** 基于不同功能划分模块（如用户管理、数据处理）
|
||||||
export default defineNuxtConfig({
|
* **按层级拆分：** 分离表现层、业务逻辑层和数据访问代码
|
||||||
modules: ['@nuxt/ui-pro'],
|
* **懒加载：** 使用`importlib.import_module()`实现按需加载，优化启动时间
|
||||||
|
* **条件导入：** 根据特定条件导入模块
|
||||||
|
|
||||||
future: {
|
## 2. 常见模式与反模式
|
||||||
compatibilityVersion: 4
|
|
||||||
},
|
|
||||||
|
|
||||||
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
|
### 2.4 状态管理最佳实践
|
||||||
pnpm install
|
|
||||||
|
|
||||||
# yarn
|
* **无状态函数：** 尽可能使用无状态函数
|
||||||
yarn install
|
* **不可变数据：** 使用不可变数据结构防止意外修改
|
||||||
|
* **显式状态：** 使用类或数据结构明确管理状态，避免全局变量
|
||||||
|
* **上下文变量：** Python 3.7+可使用`contextvars`管理异步应用中的请求级状态
|
||||||
|
|
||||||
# bun
|
### 2.5 错误处理模式
|
||||||
bun install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Development Server
|
* **捕获特定异常：** 避免笼统捕获`Exception`或`BaseException`
|
||||||
|
* **资源清理：** 使用`finally`确保清理代码必执行
|
||||||
|
* **异常日志：** 记录完整堆栈信息
|
||||||
|
* **异常消息：** 抛出包含明确错误信息的异常
|
||||||
|
* **避免异常控制流：** 异常应用于处理意外情况而非常规流程
|
||||||
|
|
||||||
Start the development server on `http://localhost:3000`:
|
## 3. 性能优化
|
||||||
|
|
||||||
```bash
|
### 3.1 优化技术
|
||||||
# npm
|
|
||||||
npm run dev
|
|
||||||
|
|
||||||
# pnpm
|
* **性能分析：** 使用`cProfile`定位瓶颈
|
||||||
pnpm run dev
|
* **高效数据结构：** 根据场景选择（如`set`用于成员测试、`dict`用于查找）
|
||||||
|
* **列表推导式与生成器：** 编写简洁高效的代码
|
||||||
|
* **NumPy向量化：** 对数值计算使用向量化操作
|
||||||
|
* **即时编译：** 性能关键代码考虑使用Numba等JIT编译器
|
||||||
|
* **字符串拼接：** 使用`''.join(iterable)`高效拼接字符串
|
||||||
|
|
||||||
# yarn
|
### 3.2 内存管理
|
||||||
yarn dev
|
|
||||||
|
|
||||||
# bun
|
* **内存分析：** 使用`memory_profiler`定位内存泄漏
|
||||||
bun run dev
|
* **`__slots__`：** 减少类实例的内存占用
|
||||||
```
|
* **生成器：** 处理大数据集时避免全部加载到内存
|
||||||
|
|
||||||
## Production
|
## 4. 安全性最佳实践
|
||||||
|
|
||||||
Build the application for production:
|
### 4.1 常见漏洞防范
|
||||||
|
|
||||||
```bash
|
* **SQL注入：** 使用参数化查询或ORM
|
||||||
# npm
|
* **XSS攻击：** 对用户输入消毒并转义输出
|
||||||
npm run build
|
* **CSRF防护：** 使用CSRF令牌
|
||||||
|
* **依赖漏洞：** 定期审计和更新依赖项
|
||||||
|
* **硬编码密钥：** 禁止在代码中硬编码密码/API密钥，使用环境变量管理
|
||||||
|
|
||||||
# pnpm
|
### 4.2 API安全通信
|
||||||
pnpm run build
|
|
||||||
|
|
||||||
# yarn
|
* **强制HTTPS：** 所有API通信必须加密
|
||||||
yarn build
|
* **速率限制：** 防止接口滥用
|
||||||
|
* **输入验证：** 处理前验证所有API请求
|
||||||
|
|
||||||
# bun
|
## 5. 测试策略
|
||||||
bun run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Locally preview production build:
|
### 5.1 单元测试要点
|
||||||
|
|
||||||
```bash
|
* **测试粒度：** 隔离测试单个函数/类/模块
|
||||||
# npm
|
* **边界条件：** 特别测试边界情况和异常场景
|
||||||
npm run preview
|
* **测试覆盖率：** 追求高覆盖率但避免教条化
|
||||||
|
|
||||||
# pnpm
|
### 5.2 集成测试建议
|
||||||
pnpm run preview
|
|
||||||
|
|
||||||
# yarn
|
* **聚焦关键流程：** 关注核心用户场景
|
||||||
yarn preview
|
* **模拟外部服务：** 使用mock替代真实外部依赖
|
||||||
|
|
||||||
# bun
|
## 6. 常见陷阱
|
||||||
bun run preview
|
|
||||||
```
|
|
||||||
|
|
||||||
Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
|
### 6.1 高频错误
|
||||||
````
|
|
||||||
|
|
||||||
::
|
* **可变默认参数：** 函数定义中避免使用可变对象作为默认值
|
||||||
:::
|
* **变量作用域：** 注意嵌套函数中的变量作用域
|
||||||
|
* **忽略异常：** 禁止直接忽略未处理的异常
|
||||||
|
* **虚拟环境：** 必须使用虚拟环境管理项目依赖
|
||||||
|
|
||||||
::code-group
|
## 7. 工具与环境
|
||||||
```md [搜索.md]
|
|
||||||
#### 此组件打开一个模态搜索框,进行搜索
|
|
||||||
::::example-fulltext-content-search
|
|
||||||
::::
|
|
||||||
|
|
||||||
#### 此组件建立一个mini搜索框,进行搜索
|
### 7.1 推荐工具链
|
||||||
::::example-fulltext-mini-search
|
|
||||||
::::
|
|
||||||
```
|
|
||||||
|
|
||||||
:::code-preview{label="预览模态组件" icon="i-lucide-eye"}
|
* **IDE：** PyCharm、VS Code（搭配Python插件）
|
||||||
::::example-fulltext-content-search
|
* **包管理：** `pip`、`poetry`
|
||||||
::::
|
* **格式化：** `black`、`autopep8`
|
||||||
:::
|
* **静态检查：** `mypy`、`pylint`
|
||||||
:::code-preview{label="预览搜索框组件" icon="i-lucide-eye"}
|
|
||||||
::::example-fulltext-mini-search
|
|
||||||
::::
|
|
||||||
:::
|
|
||||||
|
|
||||||
::
|
### 7.2 CI/CD集成
|
||||||
|
|
||||||
|
* **自动化测试：** 每次提交自动运行测试套件
|
||||||
|
* **代码质量门禁：** 集成静态分析工具到流水线
|
||||||
|
|
||||||
::tip{icon="lucide-info" color="primary" class="text-black dark:text-white"}
|
遵循这些规范和最佳实践，开发者能够构建出更健壮、可维护且安全的Python应用。
|
||||||
阅读更多关于 [`自定义组件`](/简单文档/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
|
|
||||||
@@ -1,238 +1,190 @@
|
|||||||
---
|
---
|
||||||
title: 记录生活
|
title: Coolify
|
||||||
description: 记录生活点点滴滴
|
description: Coolify是什么？
|
||||||
date: 2025-08-07
|
date: 2025-07-14
|
||||||
|
img: https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250628122847084.png
|
||||||
navigation:
|
navigation:
|
||||||
icon: lucide-house
|
icon: simple-icons:chai
|
||||||
---
|
---
|
||||||
|
# 概述
|
||||||
|
这是一份提供给AI大模型的Python代码规范与编程标准，可以有效提高Cursor等大模型对Python项目的编写能力。
|
||||||
|
|
||||||
## 博客
|
---
|
||||||
|
description: Python开发综合指南，涵盖代码组织、性能、安全性、测试等内容。这些规则旨在促进可维护、高效且安全的Python代码库。
|
||||||
|
globs: *.py
|
||||||
|
---
|
||||||
|
# Python最佳实践与编码规范
|
||||||
|
|
||||||
使用过市面上的很多文档系统，但是或多或少都有一些自己不满意的功能.
|
本文档概述了Python开发的综合最佳实践和编码标准，旨在促进编写干净、高效、可维护和安全的代码。
|
||||||
于是自己动手，丰衣足食.
|
|
||||||
同时在 Markdown 语法的基础上增加了许多**魔法(自定义组件)**,比如:
|
|
||||||
|
|
||||||
|
## 1. 代码组织与结构
|
||||||
|
|
||||||
::code-group
|
### 1.1 目录结构最佳实践
|
||||||
```mdc [index.md]
|
|
||||||
在 Markdown 中使用::card 标签,即可创建一个卡片,卡片里可以放置任何内容。比如以下内容:
|
|
||||||
::card
|
|
||||||
这里是卡片里的内容
|
|
||||||
::
|
|
||||||
```
|
|
||||||
|
|
||||||
```html [Card.vue]
|
* **扁平结构优于嵌套（但不绝对）。** 从简单结构开始，按需重构
|
||||||
<!-- Card组件: components/content/Card.vue -->
|
* **包与模块：** 使用包（包含`__init__.py`的目录）对模块进行逻辑分组
|
||||||
<template>
|
* **src布局：** 考虑使用`src`目录分离应用代码和项目级文件（setup.py、requirements.txt等），避免导入冲突并明确项目边界
|
||||||
<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
|
|
||||||
这里是卡片里的内容
|
|
||||||
::::
|
|
||||||
:::
|
|
||||||
|
|
||||||
::
|
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]
|
### 1.3 模块组织最佳实践
|
||||||
@import "tailwindcss" theme(static);
|
|
||||||
@import "@nuxt/ui-pro";
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts [app/app.config.ts]
|
* **单一职责原则：** 每个模块应有明确定义的用途
|
||||||
export default defineAppConfig({
|
* **导入规范：**
|
||||||
ui: {
|
* 顺序：标准库→第三方库→本地模块
|
||||||
colors: {
|
* 优先使用绝对导入（如`from my_package.module1 import function1`）
|
||||||
primary: 'sky',
|
* 在复杂包结构中需明确相对导入时使用显式相对导入（`from . import sibling_module`）
|
||||||
colors: 'slate'
|
* **常量：** 使用全大写定义模块级常量（如`MAX_ITERATIONS = 100`）
|
||||||
}
|
* **双下划线名称：** `__all__`、`__version__`等应放在模块文档字符串之后、所有导入之前（`from __future__`除外）。使用`__all__`显式声明公共API
|
||||||
}
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
```vue [app/app.vue]
|
### 1.4 组件架构建议
|
||||||
<template>
|
|
||||||
<UApp>
|
|
||||||
<NuxtPage />
|
|
||||||
</UApp>
|
|
||||||
</template>
|
|
||||||
```
|
|
||||||
|
|
||||||
```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]
|
### 1.5 代码分割策略
|
||||||
{
|
|
||||||
"extends": "./.nuxt/tsconfig.json"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts [nuxt.config.ts]
|
* **按功能拆分：** 基于不同功能划分模块（如用户管理、数据处理）
|
||||||
export default defineNuxtConfig({
|
* **按层级拆分：** 分离表现层、业务逻辑层和数据访问代码
|
||||||
modules: ['@nuxt/ui-pro'],
|
* **懒加载：** 使用`importlib.import_module()`实现按需加载，优化启动时间
|
||||||
|
* **条件导入：** 根据特定条件导入模块
|
||||||
|
|
||||||
future: {
|
## 2. 常见模式与反模式
|
||||||
compatibilityVersion: 4
|
|
||||||
},
|
|
||||||
|
|
||||||
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
|
### 2.4 状态管理最佳实践
|
||||||
pnpm install
|
|
||||||
|
|
||||||
# yarn
|
* **无状态函数：** 尽可能使用无状态函数
|
||||||
yarn install
|
* **不可变数据：** 使用不可变数据结构防止意外修改
|
||||||
|
* **显式状态：** 使用类或数据结构明确管理状态，避免全局变量
|
||||||
|
* **上下文变量：** Python 3.7+可使用`contextvars`管理异步应用中的请求级状态
|
||||||
|
|
||||||
# bun
|
### 2.5 错误处理模式
|
||||||
bun install
|
|
||||||
```
|
|
||||||
|
|
||||||
## Development Server
|
* **捕获特定异常：** 避免笼统捕获`Exception`或`BaseException`
|
||||||
|
* **资源清理：** 使用`finally`确保清理代码必执行
|
||||||
|
* **异常日志：** 记录完整堆栈信息
|
||||||
|
* **异常消息：** 抛出包含明确错误信息的异常
|
||||||
|
* **避免异常控制流：** 异常应用于处理意外情况而非常规流程
|
||||||
|
|
||||||
Start the development server on `http://localhost:3000`:
|
## 3. 性能优化
|
||||||
|
|
||||||
```bash
|
### 3.1 优化技术
|
||||||
# npm
|
|
||||||
npm run dev
|
|
||||||
|
|
||||||
# pnpm
|
* **性能分析：** 使用`cProfile`定位瓶颈
|
||||||
pnpm run dev
|
* **高效数据结构：** 根据场景选择（如`set`用于成员测试、`dict`用于查找）
|
||||||
|
* **列表推导式与生成器：** 编写简洁高效的代码
|
||||||
|
* **NumPy向量化：** 对数值计算使用向量化操作
|
||||||
|
* **即时编译：** 性能关键代码考虑使用Numba等JIT编译器
|
||||||
|
* **字符串拼接：** 使用`''.join(iterable)`高效拼接字符串
|
||||||
|
|
||||||
# yarn
|
### 3.2 内存管理
|
||||||
yarn dev
|
|
||||||
|
|
||||||
# bun
|
* **内存分析：** 使用`memory_profiler`定位内存泄漏
|
||||||
bun run dev
|
* **`__slots__`：** 减少类实例的内存占用
|
||||||
```
|
* **生成器：** 处理大数据集时避免全部加载到内存
|
||||||
|
|
||||||
## Production
|
## 4. 安全性最佳实践
|
||||||
|
|
||||||
Build the application for production:
|
### 4.1 常见漏洞防范
|
||||||
|
|
||||||
```bash
|
* **SQL注入：** 使用参数化查询或ORM
|
||||||
# npm
|
* **XSS攻击：** 对用户输入消毒并转义输出
|
||||||
npm run build
|
* **CSRF防护：** 使用CSRF令牌
|
||||||
|
* **依赖漏洞：** 定期审计和更新依赖项
|
||||||
|
* **硬编码密钥：** 禁止在代码中硬编码密码/API密钥，使用环境变量管理
|
||||||
|
|
||||||
# pnpm
|
### 4.2 API安全通信
|
||||||
pnpm run build
|
|
||||||
|
|
||||||
# yarn
|
* **强制HTTPS：** 所有API通信必须加密
|
||||||
yarn build
|
* **速率限制：** 防止接口滥用
|
||||||
|
* **输入验证：** 处理前验证所有API请求
|
||||||
|
|
||||||
# bun
|
## 5. 测试策略
|
||||||
bun run build
|
|
||||||
```
|
|
||||||
|
|
||||||
Locally preview production build:
|
### 5.1 单元测试要点
|
||||||
|
|
||||||
```bash
|
* **测试粒度：** 隔离测试单个函数/类/模块
|
||||||
# npm
|
* **边界条件：** 特别测试边界情况和异常场景
|
||||||
npm run preview
|
* **测试覆盖率：** 追求高覆盖率但避免教条化
|
||||||
|
|
||||||
# pnpm
|
### 5.2 集成测试建议
|
||||||
pnpm run preview
|
|
||||||
|
|
||||||
# yarn
|
* **聚焦关键流程：** 关注核心用户场景
|
||||||
yarn preview
|
* **模拟外部服务：** 使用mock替代真实外部依赖
|
||||||
|
|
||||||
# bun
|
## 6. 常见陷阱
|
||||||
bun run preview
|
|
||||||
```
|
|
||||||
|
|
||||||
Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
|
### 6.1 高频错误
|
||||||
````
|
|
||||||
|
|
||||||
::
|
* **可变默认参数：** 函数定义中避免使用可变对象作为默认值
|
||||||
:::
|
* **变量作用域：** 注意嵌套函数中的变量作用域
|
||||||
|
* **忽略异常：** 禁止直接忽略未处理的异常
|
||||||
|
* **虚拟环境：** 必须使用虚拟环境管理项目依赖
|
||||||
|
|
||||||
::code-group
|
## 7. 工具与环境
|
||||||
```md [搜索.md]
|
|
||||||
#### 此组件打开一个模态搜索框,进行搜索
|
|
||||||
::::example-fulltext-content-search
|
|
||||||
::::
|
|
||||||
|
|
||||||
#### 此组件建立一个mini搜索框,进行搜索
|
### 7.1 推荐工具链
|
||||||
::::example-fulltext-mini-search
|
|
||||||
::::
|
|
||||||
```
|
|
||||||
|
|
||||||
:::code-preview{label="预览模态组件" icon="i-lucide-eye"}
|
* **IDE：** PyCharm、VS Code（搭配Python插件）
|
||||||
::::example-fulltext-content-search
|
* **包管理：** `pip`、`poetry`
|
||||||
::::
|
* **格式化：** `black`、`autopep8`
|
||||||
:::
|
* **静态检查：** `mypy`、`pylint`
|
||||||
:::code-preview{label="预览搜索框组件" icon="i-lucide-eye"}
|
|
||||||
::::example-fulltext-mini-search
|
|
||||||
::::
|
|
||||||
:::
|
|
||||||
|
|
||||||
::
|
### 7.2 CI/CD集成
|
||||||
|
|
||||||
|
* **自动化测试：** 每次提交自动运行测试套件
|
||||||
|
* **代码质量门禁：** 集成静态分析工具到流水线
|
||||||
|
|
||||||
::tip{icon="lucide-info" color="primary" class="text-black dark:text-white"}
|
遵循这些规范和最佳实践，开发者能够构建出更健壮、可维护且安全的Python应用。
|
||||||
阅读更多关于 [`自定义组件`](/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
|
|
||||||
Reference in New Issue
Block a user