589 lines
14 KiB
Markdown
589 lines
14 KiB
Markdown
# 代码风格指南
|
||
|
||
<div align="center">
|
||
|
||
**🌍 Language / 语言**
|
||
|
||
[🇺🇸 English](./Code-Style.en.md) | [🇨🇳 中文](./Code-Style.md)
|
||
|
||
</div>
|
||
|
||
本指南概述了 AI Proxy Worker 项目的编码标准和最佳实践。遵循这些准则确保整个项目的代码一致性、可维护性和可读性。
|
||
|
||
## 📋 通用原则
|
||
|
||
### 代码质量标准
|
||
- **可读性优先**：编写能讲述故事的代码
|
||
- **一致性**：在整个代码库中遵循既定模式
|
||
- **简洁性**：优先选择简单的解决方案而非复杂的
|
||
- **模块化设计**：拆分复杂函数为单一职责的小函数
|
||
- **低认知复杂度**：保持函数的认知复杂度在15以下
|
||
- **性能**：考虑代码的性能影响
|
||
- **安全性**：在实现中始终优先考虑安全性
|
||
|
||
### 文件组织
|
||
```
|
||
ai-proxy-worker/
|
||
├── worker.js # 主要 worker 脚本
|
||
├── wrangler.toml # 配置文件
|
||
├── docs/ # 文档
|
||
├── examples/ # 使用示例
|
||
└── tests/ # 测试文件（未来）
|
||
```
|
||
|
||
## 🔧 JavaScript/TypeScript 标准
|
||
|
||
### 代码格式化
|
||
- **缩进**：使用 2 个空格（不使用制表符）
|
||
- **行长度**：每行最多 100 个字符
|
||
- **分号**：可选，但要保持一致
|
||
- **引号**：字符串使用单引号
|
||
- **尾随逗号**：在多行对象/数组中使用尾随逗号
|
||
|
||
```javascript
|
||
// ✅ 好的示例
|
||
const config = {
|
||
apiUrl: 'https://api.deepseek.com',
|
||
timeout: 30000,
|
||
retries: 3,
|
||
}
|
||
|
||
const models = [
|
||
'deepseek-chat',
|
||
'deepseek-reasoner',
|
||
]
|
||
|
||
// ❌ 避免这样写
|
||
const config = {
|
||
"apiUrl": "https://api.deepseek.com",
|
||
"timeout": 30000,
|
||
"retries": 3
|
||
};
|
||
```
|
||
|
||
### 命名约定
|
||
|
||
#### 变量和函数
|
||
变量和函数使用 camelCase：
|
||
|
||
```javascript
|
||
// ✅ 好的示例
|
||
const apiResponse = await fetchData()
|
||
const userMessage = request.body.message
|
||
const isValidRequest = validateInput(data)
|
||
|
||
function processUserRequest(request) {
|
||
// 实现
|
||
}
|
||
|
||
async function sendUpstreamRequest(payload) {
|
||
// 实现
|
||
}
|
||
|
||
// ❌ 避免这样写
|
||
const api_response = await fetchData()
|
||
const user_message = request.body.message
|
||
const IsValidRequest = validateInput(data)
|
||
|
||
function ProcessUserRequest(request) {
|
||
// 实现
|
||
}
|
||
```
|
||
|
||
#### 常量
|
||
常量使用 UPPER_SNAKE_CASE：
|
||
|
||
```javascript
|
||
// ✅ 好的示例
|
||
const API_BASE_URL = 'https://api.deepseek.com'
|
||
const DEFAULT_TIMEOUT = 30000
|
||
const MAX_RETRIES = 3
|
||
const SUPPORTED_MODELS = ['deepseek-chat', 'deepseek-reasoner']
|
||
|
||
// ❌ 避免这样写
|
||
const apiBaseUrl = 'https://api.deepseek.com'
|
||
const defaultTimeout = 30000
|
||
```
|
||
|
||
#### 类和对象
|
||
类和构造函数使用 PascalCase：
|
||
|
||
```javascript
|
||
// ✅ 好的示例
|
||
class RequestHandler {
|
||
constructor(config) {
|
||
this.config = config
|
||
}
|
||
}
|
||
|
||
class ApiError extends Error {
|
||
constructor(message, statusCode) {
|
||
super(message)
|
||
this.statusCode = statusCode
|
||
}
|
||
}
|
||
|
||
// ❌ 避免这样写
|
||
class requestHandler {
|
||
// 实现
|
||
}
|
||
```
|
||
|
||
### 函数结构
|
||
|
||
#### 函数声明
|
||
短函数优先使用箭头函数，复杂逻辑使用常规函数：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 短工具函数
|
||
const isValidModel = (model) => SUPPORTED_MODELS.includes(model)
|
||
const createErrorResponse = (message, status = 400) =>
|
||
new Response(JSON.stringify({ error: message }), { status })
|
||
|
||
// ✅ 好的示例 - 复杂函数
|
||
async function handleChatRequest(request, env) {
|
||
try {
|
||
// 验证请求
|
||
const validation = await validateRequest(request)
|
||
if (!validation.valid) {
|
||
return createErrorResponse(validation.error, 400)
|
||
}
|
||
|
||
// 处理请求
|
||
const response = await processChat(request, env)
|
||
return response
|
||
|
||
} catch (error) {
|
||
console.error('聊天请求失败:', error)
|
||
return createErrorResponse('内部服务器错误', 500)
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 参数处理
|
||
对象参数使用解构：
|
||
|
||
```javascript
|
||
// ✅ 好的示例
|
||
async function processChat({ messages, model, temperature }, env) {
|
||
// 实现
|
||
}
|
||
|
||
// 带验证的替代方案
|
||
async function processChat(params, env) {
|
||
const { messages, model, temperature = 0.7 } = params
|
||
|
||
// 验证必需参数
|
||
if (!messages || !model) {
|
||
throw new Error('缺少必需参数')
|
||
}
|
||
|
||
// 实现
|
||
}
|
||
|
||
// ❌ 避免这样写
|
||
async function processChat(params, env) {
|
||
const messages = params.messages
|
||
const model = params.model
|
||
const temperature = params.temperature
|
||
// 实现
|
||
}
|
||
```
|
||
|
||
## 📝 文档标准
|
||
|
||
### JSDoc 注释
|
||
函数文档使用 JSDoc：
|
||
|
||
```javascript
|
||
/**
|
||
* 向上游 API 发送聊天请求
|
||
* @param {Object} request - 聊天请求对象
|
||
* @param {Array} request.messages - 聊天消息数组
|
||
* @param {string} request.model - 要使用的模型
|
||
* @param {number} [request.temperature=0.7] - 采样温度
|
||
* @param {Object} env - 环境变量
|
||
* @param {string} env.DEEPSEEK_API_KEY - DeepSeek API 密钥
|
||
* @returns {Promise<Response>} API 响应
|
||
* @throws {Error} 当 API 密钥缺失或请求失败时
|
||
*/
|
||
async function sendChatRequest(request, env) {
|
||
// 实现
|
||
}
|
||
```
|
||
|
||
### 行内注释
|
||
使用注释解释复杂逻辑：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 解释"为什么"
|
||
async function handleRequest(request, env) {
|
||
// 提取客户端 IP 用于速率限制
|
||
const clientIP = request.headers.get('CF-Connecting-IP') ||
|
||
request.headers.get('X-Forwarded-For') ||
|
||
'unknown'
|
||
|
||
// 在处理昂贵操作之前检查速率限制
|
||
if (!await checkRateLimit(clientIP)) {
|
||
return new Response('超出速率限制', { status: 429 })
|
||
}
|
||
|
||
// 处理实际请求
|
||
return await processRequest(request, env)
|
||
}
|
||
|
||
// ❌ 避免这样写 - 陈述显而易见的事实
|
||
async function handleRequest(request, env) {
|
||
// 获取客户端 IP
|
||
const clientIP = request.headers.get('CF-Connecting-IP')
|
||
|
||
// 返回速率限制响应
|
||
if (!await checkRateLimit(clientIP)) {
|
||
return new Response('超出速率限制', { status: 429 })
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 模块化验证架构
|
||
|
||
### 验证函数设计原则
|
||
|
||
本项目采用模块化验证架构，将复杂的验证逻辑拆分为多个单一职责的函数：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 模块化验证
|
||
async function validateRequest(request) {
|
||
validateContentType(request); // 验证Content-Type
|
||
validateContentLength(request); // 验证请求大小
|
||
|
||
if (CONFIG.VALIDATE_REQUEST_BODY) {
|
||
await validateRequestBody(request); // 验证请求体
|
||
}
|
||
}
|
||
|
||
function validateContentType(request) {
|
||
const contentType = request.headers.get('content-type') || '';
|
||
if (!contentType.includes('application/json')) {
|
||
throw new Error('Invalid content type. Expected application/json');
|
||
}
|
||
}
|
||
|
||
async function validateRequestBody(request) {
|
||
try {
|
||
const body = await request.clone().json();
|
||
validateMessages(body.messages); // 验证消息数组
|
||
validateModel(body.model); // 验证模型
|
||
} catch (e) {
|
||
// 错误处理逻辑
|
||
}
|
||
}
|
||
```
|
||
|
||
### 函数复杂度控制
|
||
|
||
- **认知复杂度限制**: 每个函数保持认知复杂度 ≤ 15
|
||
- **单一职责原则**: 每个验证函数只负责一种验证
|
||
- **可组合性**: 验证函数可以独立测试和复用
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 单一职责
|
||
function validateSingleMessage(message) {
|
||
if (!message.role || !message.content) {
|
||
throw new Error('Invalid request format. Each message must have role and content');
|
||
}
|
||
if (!['system', 'user', 'assistant', 'tool'].includes(message.role)) {
|
||
throw new Error('Invalid request format. Invalid message role');
|
||
}
|
||
}
|
||
|
||
// ❌ 避免这样写 - 复杂的巨大函数
|
||
function validateEverything(request) {
|
||
// 100+ 行验证代码，认知复杂度 > 20
|
||
}
|
||
```
|
||
|
||
## 🛡️ 错误处理
|
||
|
||
### 错误响应格式
|
||
使用一致的错误响应格式：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 一致的错误格式
|
||
function createErrorResponse(error, statusCode = 500, details = null) {
|
||
const errorResponse = {
|
||
error: error.code || 'unknown_error',
|
||
message: error.message || '发生意外错误',
|
||
timestamp: new Date().toISOString(),
|
||
}
|
||
|
||
// 在开发/调试模式下添加详细信息
|
||
if (details && env.DEBUG_MODE === 'true') {
|
||
errorResponse.details = details
|
||
}
|
||
|
||
return new Response(JSON.stringify(errorResponse), {
|
||
status: statusCode,
|
||
headers: { 'Content-Type': 'application/json' }
|
||
})
|
||
}
|
||
|
||
// 使用方法
|
||
try {
|
||
const result = await riskyOperation()
|
||
return new Response(JSON.stringify(result))
|
||
} catch (error) {
|
||
console.error('操作失败:', error)
|
||
return createErrorResponse(error, 500, { operation: 'riskyOperation' })
|
||
}
|
||
```
|
||
|
||
### 错误类型
|
||
为不同场景定义自定义错误类型：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 自定义错误类
|
||
class ValidationError extends Error {
|
||
constructor(message, field = null) {
|
||
super(message)
|
||
this.name = 'ValidationError'
|
||
this.code = 'validation_error'
|
||
this.field = field
|
||
}
|
||
}
|
||
|
||
class ApiError extends Error {
|
||
constructor(message, statusCode = 500, originalError = null) {
|
||
super(message)
|
||
this.name = 'ApiError'
|
||
this.code = 'api_error'
|
||
this.statusCode = statusCode
|
||
this.originalError = originalError
|
||
}
|
||
}
|
||
|
||
// 使用方法
|
||
function validateChatRequest(data) {
|
||
if (!data.messages || !Array.isArray(data.messages)) {
|
||
throw new ValidationError('消息必须是数组', 'messages')
|
||
}
|
||
|
||
if (!data.model || typeof data.model !== 'string') {
|
||
throw new ValidationError('模型必须是字符串', 'model')
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔒 安全最佳实践
|
||
|
||
### 输入验证
|
||
始终验证和清理输入：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 全面验证
|
||
function validateChatRequest(data) {
|
||
const errors = []
|
||
|
||
// 必需字段
|
||
if (!data.messages || !Array.isArray(data.messages)) {
|
||
errors.push('messages 必须是数组')
|
||
}
|
||
|
||
if (!data.model || typeof data.model !== 'string') {
|
||
errors.push('model 必须是字符串')
|
||
}
|
||
|
||
// 验证消息数组
|
||
if (data.messages) {
|
||
data.messages.forEach((msg, index) => {
|
||
if (!msg.role || !['user', 'assistant', 'system'].includes(msg.role)) {
|
||
errors.push(`messages[${index}].role 必须是 user、assistant 或 system`)
|
||
}
|
||
|
||
if (!msg.content || typeof msg.content !== 'string') {
|
||
errors.push(`messages[${index}].content 必须是非空字符串`)
|
||
}
|
||
|
||
// 内容长度限制
|
||
if (msg.content && msg.content.length > 100000) {
|
||
errors.push(`messages[${index}].content 超过最大长度`)
|
||
}
|
||
})
|
||
}
|
||
|
||
// 可选参数验证
|
||
if (data.temperature !== undefined) {
|
||
if (typeof data.temperature !== 'number' ||
|
||
data.temperature < 0 ||
|
||
data.temperature > 2) {
|
||
errors.push('temperature 必须是 0 到 2 之间的数字')
|
||
}
|
||
}
|
||
|
||
return {
|
||
valid: errors.length === 0,
|
||
errors
|
||
}
|
||
}
|
||
```
|
||
|
||
### 敏感数据处理
|
||
永远不要记录敏感信息：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 清理后的日志
|
||
function logRequest(request, response) {
|
||
const logData = {
|
||
method: request.method,
|
||
url: new URL(request.url).pathname, // 不记录查询参数
|
||
status: response.status,
|
||
timestamp: new Date().toISOString(),
|
||
// 不记录授权头或正文内容
|
||
}
|
||
|
||
console.log('请求已处理:', logData)
|
||
}
|
||
|
||
// ❌ 避免这样写 - 记录敏感数据
|
||
function logRequest(request, response) {
|
||
console.log('请求:', {
|
||
headers: Object.fromEntries(request.headers), // 包含 API 密钥！
|
||
body: request.body, // 包含用户数据！
|
||
url: request.url // 可能包含敏感查询参数！
|
||
})
|
||
}
|
||
```
|
||
|
||
## ⚡ 性能指南
|
||
|
||
### Async/Await 最佳实践
|
||
正确使用 async/await：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 尽可能并行执行
|
||
async function processMultipleRequests(requests, env) {
|
||
// 并行执行请求
|
||
const promises = requests.map(request => processRequest(request, env))
|
||
const results = await Promise.allSettled(promises)
|
||
|
||
return results.map(result =>
|
||
result.status === 'fulfilled' ? result.value : null
|
||
).filter(Boolean)
|
||
}
|
||
|
||
// ✅ 好的示例 - 需要时顺序执行
|
||
async function processWithDependencies(request, env) {
|
||
const validation = await validateRequest(request)
|
||
if (!validation.valid) {
|
||
throw new ValidationError(validation.errors.join(', '))
|
||
}
|
||
|
||
const processed = await processRequest(request, env)
|
||
const logged = await logRequest(processed)
|
||
|
||
return processed
|
||
}
|
||
|
||
// ❌ 避免这样写 - 不必要的顺序执行
|
||
async function processMultipleRequests(requests, env) {
|
||
const results = []
|
||
for (const request of requests) {
|
||
const result = await processRequest(request, env) // 阻塞！
|
||
results.push(result)
|
||
}
|
||
return results
|
||
}
|
||
```
|
||
|
||
### 内存管理
|
||
注意内存使用：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 清理资源
|
||
async function processLargeRequest(request, env) {
|
||
let reader = null
|
||
try {
|
||
reader = request.body.getReader()
|
||
const chunks = []
|
||
|
||
while (true) {
|
||
const { done, value } = await reader.read()
|
||
if (done) break
|
||
chunks.push(value)
|
||
}
|
||
|
||
return await processChunks(chunks)
|
||
|
||
} finally {
|
||
// 清理资源
|
||
if (reader) {
|
||
reader.releaseLock()
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🧪 测试指南
|
||
|
||
### 测试结构
|
||
编写测试时（未来实现）：
|
||
|
||
```javascript
|
||
// ✅ 好的示例 - 清晰的测试结构
|
||
describe('聊天请求处理器', () => {
|
||
describe('validateChatRequest', () => {
|
||
it('应该接受有效的聊天请求', () => {
|
||
const validRequest = {
|
||
messages: [{ role: 'user', content: '你好' }],
|
||
model: 'deepseek-chat'
|
||
}
|
||
|
||
const result = validateChatRequest(validRequest)
|
||
expect(result.valid).toBe(true)
|
||
})
|
||
|
||
it('应该拒绝没有消息的请求', () => {
|
||
const invalidRequest = { model: 'deepseek-chat' }
|
||
|
||
const result = validateChatRequest(invalidRequest)
|
||
expect(result.valid).toBe(false)
|
||
expect(result.errors).toContain('messages 必须是数组')
|
||
})
|
||
})
|
||
})
|
||
```
|
||
|
||
## 📋 代码审查清单
|
||
|
||
提交代码前，确保：
|
||
|
||
### 功能性
|
||
- [ ] 代码按预期工作
|
||
- [ ] 处理边界情况
|
||
- [ ] 正确管理错误条件
|
||
- [ ] 考虑性能影响
|
||
|
||
### 代码质量
|
||
- [ ] 遵循项目命名约定
|
||
- [ ] 函数大小合理（< 50 行）
|
||
- [ ] 代码自文档化
|
||
- [ ] 复杂逻辑有注释
|
||
- [ ] 没有遗留调试代码
|
||
|
||
### 安全性
|
||
- [ ] 实现输入验证
|
||
- [ ] 日志中无敏感数据
|
||
- [ ] 适当的错误处理不泄露信息
|
||
- [ ] 适当设置安全头
|
||
|
||
### 文档
|
||
- [ ] 公共函数有 JSDoc 注释
|
||
- [ ] 需要时更新 README
|
||
- [ ] 为新功能提供示例
|
||
- [ ] 记录重大变更
|
||
|
||
---
|
||
|
||
**一致的代码风格让协作更容易** ✨
|
||
|
||
遵循这些指南有助于维护高质量、可维护的代码库，让所有贡献者都能轻松使用。
|