@umacloud/knowledge 1.0.1

package/development/01-standards/mongodb-complete.md

@@ -0,0 +1,406 @@
+---
+id: mongodb-complete
+title: MongoDB完整指南
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [complete, development, mongodb, python客户端, 学习路径, 最佳实践, 核心概念, 概述]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# MongoDB完整指南
+
+## 概述
+MongoDB是NoSQL文档数据库,存储JSON格式的文档,支持灵活的schema、水平扩展和丰富的查询语言。本指南覆盖CRUD操作、聚合管道、索引和最佳实践。
+
+## 核心概念
+
+### 1. 文档模型
+
+**数据库和集合**:
+```javascript
+// 创建/切换数据库
+use mydb
+
+// 创建集合
+db.createCollection('users')
+
+// 插入文档(自动创建集合)
+db.users.insertOne({
+  name: 'Alice',
+  age: 30,
+  email: 'alice@example.com',
+  tags: ['developer', 'python'],
+  address: {
+    city: 'Beijing',
+    country: 'China'
+  }
+})
+
+// 批量插入
+db.users.insertMany([
+  { name: 'Bob', age: 25 },
+  { name: 'Carol', age: 28 }
+])
+```
+
+### 2. CRUD操作
+
+**查询**:
+```javascript
+// 查询所有
+db.users.find()
+
+// 条件查询
+db.users.find({ age: { $gte: 25 } })
+
+// 投影(只返回指定字段)
+db.users.find({}, { name: 1, email: 1, _id: 0 })
+
+// 排序
+db.users.find().sort({ age: -1 })  // 降序
+
+// 分页
+db.users.find().skip(10).limit(10)
+
+// 比较运算符
+db.users.find({
+  age: { 
+    $eq: 30,    // 等于
+    $ne: 25,    // 不等于
+    $gt: 20,    // 大于
+    $gte: 25,   // 大于等于
+    $lt: 40,    // 小于
+    $lte: 35    // 小于等于
+  }
+})
+
+// 逻辑运算符
+db.users.find({
+  $and: [
+    { age: { $gte: 25 } },
+    { status: 'active' }
+  ]
+})
+
+db.users.find({
+  $or: [
+    { age: { $lt: 20 } },
+    { age: { $gt: 30 } }
+  ]
+})
+
+// 数组查询
+db.users.find({ tags: 'python' })  // 包含
+db.users.find({ tags: { $all: ['python', 'mongodb'] } })  // 包含所有
+db.users.find({ tags: { $size: 3 } })  // 数组长度
+
+// 嵌套文档查询
+db.users.find({ 'address.city': 'Beijing' })
+```
+
+**更新**:
+```javascript
+// 更新单个文档
+db.users.updateOne(
+  { name: 'Alice' },
+  { $set: { age: 31, status: 'active' } }
+)
+
+// 更新多个文档
+db.users.updateMany(
+  { age: { $lt: 30 } },
+  { $set: { category: 'young' } }
+)
+
+// 替换文档
+db.users.replaceOne(
+  { name: 'Alice' },
+  { name: 'Alice', age: 32 }
+)
+
+// 更新操作符
+db.users.updateOne(
+  { name: 'Alice' },
+  {
+    $set: { age: 32 },           // 设置字段
+    $unset: { tempField: 1 },    // 删除字段
+    $inc: { score: 10 },         // 增加数值
+    $push: { tags: 'golang' },   // 添加到数组
+    $pull: { tags: 'old' },      // 从数组删除
+    $addToSet: { tags: 'unique' } // 添加唯一值
+  }
+)
+```
+
+**删除**:
+```javascript
+// 删除单个文档
+db.users.deleteOne({ name: 'Alice' })
+
+// 删除多个文档
+db.users.deleteMany({ status: 'inactive' })
+
+// 删除所有文档
+db.users.deleteMany({})
+
+// 删除集合
+db.users.drop()
+```
+
+### 3. 聚合管道
+
+```javascript
+// 基本聚合
+db.orders.aggregate([
+  // 匹配阶段
+  { $match: { status: 'completed' } },
+  
+  // 分组阶段
+  {
+    $group: {
+      _id: '$customerId',
+      totalAmount: { $sum: '$amount' },
+      count: { $sum: 1 },
+      avgAmount: { $avg: '$amount' }
+    }
+  },
+  
+  // 排序
+  { $sort: { totalAmount: -1 } },
+  
+  // 限制
+  { $limit: 10 }
+])
+
+// lookup(关联查询)
+db.orders.aggregate([
+  {
+    $lookup: {
+      from: 'customers',
+      localField: 'customerId',
+      foreignField: '_id',
+      as: 'customer'
+    }
+  },
+  {
+    $unwind: '$customer'  // 展开数组
+  },
+  {
+    $project: {
+      orderId: '$_id',
+      amount: 1,
+      customerName: '$customer.name'
+    }
+  }
+])
+
+// 文本搜索
+db.articles.createIndex({ content: 'text' })
+
+db.articles.aggregate([
+  {
+    $match: {
+      $text: { $search: 'mongodb database' }
+    }
+  },
+  {
+    $addFields: {
+      score: { $meta: 'textScore' }
+    }
+  },
+  {
+    $sort: { score: -1 }
+  }
+])
+```
+
+### 4. 索引
+
+```javascript
+// 创建索引
+db.users.createIndex({ email: 1 })  // 升序
+db.users.createIndex({ name: 1, age: -1 })  // 复合索引
+
+// 唯一索引
+db.users.createIndex({ email: 1 }, { unique: true })
+
+// 文本索引
+db.articles.createIndex({ title: 'text', content: 'text' })
+
+// 地理空间索引
+db.places.createIndex({ location: '2dsphere' })
+
+// 查看索引
+db.users.getIndexes()
+
+// 删除索引
+db.users.dropIndex('index_name')
+
+// 查询计划
+db.users.find({ email: 'alice@example.com' }).explain('executionStats')
+```
+
+### 5. 事务
+
+```javascript
+// MongoDB 4.0+ 支持多文档事务
+const session = db.getMongo().startSession()
+
+try {
+  session.startTransaction()
+  
+  const usersCollection = session.getDatabase('mydb').users
+  const ordersCollection = session.getDatabase('mydb').orders
+  
+  // 操作1
+  await usersCollection.updateOne(
+    { _id: userId },
+    { $inc: { balance: -100 } },
+    { session }
+  )
+  
+  // 操作2
+  await ordersCollection.insertOne(
+    { userId, amount: 100 },
+    { session }
+  )
+  
+  await session.commitTransaction()
+  console.log('Transaction committed')
+} catch (error) {
+  await session.abortTransaction()
+  console.error('Transaction aborted:', error)
+} finally {
+  await session.endSession()
+}
+```
+
+## Python客户端
+
+```python
+from pymongo import MongoClient
+from bson.objectid import ObjectId
+
+# 连接
+client = MongoClient('mongodb://localhost:27017/')
+db = client['mydb']
+users = db['users']
+
+# 插入
+user_id = users.insert_one({
+    'name': 'Alice',
+    'age': 30,
+    'email': 'alice@example.com'
+}).inserted_id
+
+# 查询
+user = users.find_one({'_id': ObjectId(user_id)})
+all_users = list(users.find({'age': {'$gte': 25}}))
+
+# 更新
+users.update_one(
+    {'name': 'Alice'},
+    {'$set': {'age': 31}}
+)
+
+# 删除
+users.delete_one({'name': 'Alice'})
+
+# 聚合
+pipeline = [
+    {'$match': {'age': {'$gte': 25}}},
+    {'$group': {'_id': '$status', 'count': {'$sum': 1}}}
+]
+results = list(users.aggregate(pipeline))
+```
+
+## 最佳实践
+
+### ✅ DO
+
+1. **使用索引**
+```javascript
+// ✅ 好: 查询走索引
+db.users.createIndex({ email: 1 })
+db.users.find({ email: 'alice@example.com' })
+
+// ❌ 差: 全表扫描
+db.users.find({ $where: 'this.email.length > 10' })
+```
+
+2. **使用投影减少数据传输**
+```javascript
+// ✅ 好
+db.users.find({}, { name: 1, email: 1, _id: 0 })
+
+// ❌ 差
+db.users.find({})  // 返回所有字段
+```
+
+3. **批量操作**
+```python
+# ✅ 好
+users.insert_many([doc1, doc2, doc3])
+
+# ❌ 差
+for doc in docs:
+    users.insert_one(doc)
+```
+
+### ❌ DON'T
+
+1. **不要使用大文档**
+```javascript
+// ❌ 差: 文档超过16MB
+{
+  logs: [ /* 数百万条日志 */ ]
+}
+
+// ✅ 好: 分离到单独集合
+db.logs.insertMany([log1, log2, ...])
+```
+
+2. **不要过度使用$lookup**
+```javascript
+// ❌ 差: 多层嵌套lookup
+db.orders.aggregate([
+  { $lookup: { ... } },
+  { $lookup: { ... } },
+  { $lookup: { ... } }
+])
+
+// ✅ 好: 考虑嵌入文档或反范式化
+```
+
+## 学习路径
+
+### 初级 (1-2周)
+1. 文档模型
+2. CRUD操作
+3. 基本查询
+
+### 中级 (2-3周)
+1. 聚合管道
+2. 索引优化
+3. 数据建模
+
+### 高级 (2-4周)
+1. 事务
+2. 分片
+3. 复制集
+
+### 专家级 (持续)
+1. 性能调优
+2. 高可用架构
+3. 大规模部署
+
+---
+
+**知识ID**: `mongodb-complete`  
+**领域**: development  
+**类型**: standards  
+**难度**: intermediate  
+**质量分**: 93  
+**维护者**: dba-team@umadev.com  
+**最后更新**: 2026-03-28

package/development/01-standards/oauth2-complete.md

@@ -0,0 +1,285 @@
+---
+id: oauth2-complete
+title: OAuth2.0完整指南
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [complete, development, oauth2, 学习路径, 最佳实践, 核心概念, 概述]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# OAuth2.0完整指南
+
+## 概述
+OAuth2.0是授权框架,允许第三方应用访问用户资源而无需暴露密码。本指南覆盖授权流程、令牌管理、JWT和最佳实践。
+
+## 核心概念
+
+### 1. 四种授权模式
+
+**授权码(Authorization Code)**:
+```python
+# 用于服务器端应用
+from authlib.integrations.flask_oauth2 import AuthorizationServer
+
+# 授权端点
+@app.route('/oauth/authorize', methods=['GET', 'POST'])
+def authorize():
+    # 验证用户
+    user = current_user()
+    
+    # 生成授权码
+    grant = authorization_server.validate_authorization_request()
+    return grant.create_authorization_response()
+
+# 令牌端点
+@app.route('/oauth/token', methods=['POST'])
+def issue_token():
+    return authorization_server.create_token_response()
+```
+
+**隐式(Implicit)** - 已弃用,不推荐
+
+**密码模式(Resource Owner Password Credentials)** - 已弃用
+
+**客户端凭证(Client Credentials)**:
+```python
+# 用于机器对机器通信
+@app.route('/oauth/token', methods=['POST'])
+def client_credentials():
+    grant = authorization_server.validate_token_request()
+    return grant.create_token_response()
+```
+
+### 2. JWT令牌
+
+**生成JWT**:
+```python
+import jwt
+from datetime import datetime, timedelta
+
+def generate_jwt(user_id: int) -> str:
+    payload = {
+        'sub': user_id,
+        'iat': datetime.utcnow(),
+        'exp': datetime.utcnow() + timedelta(hours=1),
+        'scope': 'read write'
+    }
+    
+    token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')
+    return token
+
+def verify_jwt(token: str) -> dict:
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
+        return payload
+    except jwt.ExpiredSignatureError:
+        raise ValueError('Token expired')
+    except jwt.InvalidTokenError:
+        raise ValueError('Invalid token')
+```
+
+**刷新令牌**:
+```python
+def refresh_access_token(refresh_token: str) -> str:
+    # 验证刷新令牌
+    payload = verify_jwt(refresh_token)
+    
+    # 检查是否在黑名单
+    if is_token_revoked(refresh_token):
+        raise ValueError('Token revoked')
+    
+    # 生成新访问令牌
+    new_access_token = generate_jwt(payload['sub'])
+    return new_access_token
+```
+
+### 3. OpenID Connect
+
+**Google OAuth2**:
+```python
+from authlib.integrations.flask_client import OAuth
+
+oauth = OAuth()
+
+google = oauth.register(
+    'google',
+    client_id='YOUR_CLIENT_ID',
+    client_secret='YOUR_CLIENT_SECRET',
+    server_metadata_url='https://accounts.google.com/.well-known/openid-configuration',
+    client_kwargs={'scope': 'openid email profile'}
+)
+
+@app.route('/login/google')
+def login_google():
+    redirect_uri = url_for('authorize_google', _external=True)
+    return google.authorize_redirect(redirect_uri)
+
+@app.route('/auth/google')
+def authorize_google():
+    token = google.authorize_access_token()
+    user_info = google.parse_id_token(token)
+    
+    # 创建或获取用户
+    user = get_or_create_user(user_info)
+    
+    # 生成本地JWT
+    access_token = generate_jwt(user.id)
+    
+    return {'access_token': access_token}
+```
+
+### 4. FastAPI集成
+
+```python
+from fastapi import FastAPI, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from passlib.context import CryptContext
+
+app = FastAPI()
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl='token')
+pwd_context = CryptContext(schemes=['bcrypt'], deprecated='auto')
+
+# 获取当前用户
+async def get_current_user(token: str = Depends(oauth2_scheme)):
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail='Could not validate credentials',
+        headers={'WWW-Authenticate': 'Bearer'},
+    )
+    
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
+        user_id: int = payload.get('sub')
+        if user_id is None:
+            raise credentials_exception
+    except jwt.JWTError:
+        raise credentials_exception
+    
+    user = get_user(user_id)
+    if user is None:
+        raise credentials_exception
+    
+    return user
+
+# 登录端点
+@app.post('/token')
+async def login(form_data: OAuth2PasswordRequestForm = Depends()):
+    user = authenticate_user(form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail='Incorrect username or password',
+            headers={'WWW-Authenticate': 'Bearer'},
+        )
+    
+    access_token = generate_jwt(user.id)
+    return {'access_token': access_token, 'token_type': 'bearer'}
+
+# 受保护端点
+@app.get('/users/me')
+async def read_users_me(current_user = Depends(get_current_user)):
+    return current_user
+```
+
+### 5. 权限和作用域
+
+```python
+from functools import wraps
+
+def require_scope(required_scope: str):
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, token: str = Depends(oauth2_scheme), **kwargs):
+            payload = verify_jwt(token)
+            scopes = payload.get('scope', '').split()
+            
+            if required_scope not in scopes:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail='Insufficient permissions'
+                )
+            
+            return await func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+# 使用装饰器
+@app.get('/admin/users')
+@require_scope('admin')
+async def list_all_users():
+    return get_all_users()
+```
+
+## 最佳实践
+
+### ✅ DO
+
+1. **使用HTTPS**
+```python
+# ✅ 好
+from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
+app.add_middleware(HTTPSRedirectMiddleware)
+```
+
+2. **短有效期访问令牌**
+```python
+# ✅ 好
+access_token_expires = timedelta(minutes=15)
+refresh_token_expires = timedelta(days=7)
+```
+
+3. **令牌撤销**
+```python
+# 使用Redis黑名单
+def revoke_token(token: str):
+    redis.setex(f'revoked:{token}', 3600, '1')
+```
+
+### ❌ DON'T
+
+1. **不要在URL中传递令牌**
+```python
+# ❌ 差
+GET /api/users?token=xxx
+
+# ✅ 好
+GET /api/users
+Authorization: Bearer xxx
+```
+
+2. **不要存储明文密码**
+```python
+# ❌ 差
+password = 'user_password'
+
+# ✅ 好
+hashed = pwd_context.hash(password)
+```
+
+## 学习路径
+
+### 初级 (1周)
+1. OAuth2.0基础概念
+2. 授权流程
+3. 令牌使用
+
+### 中级 (1-2周)
+1. JWT实现
+2. OpenID Connect
+3. FastAPI集成
+
+### 高级 (2-3周)
+1. 权限管理
+2. 令牌撤销
+3. 安全审计
+
+---
+
+**知识ID**: `oauth2-complete`  
+**领域**: development  
+**类型**: standards  
+**难度**: intermediate  
+**质量分**: 93  
+**维护者**: security-team@umadev.com  
+**最后更新**: 2026-03-28