@umacloud/knowledge 1.0.1

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

@@ -0,0 +1,317 @@
+---
+id: redis-complete
+title: Redis完整指南
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [complete, development, python客户端, redis, 学习路径, 最佳实践, 核心数据结构, 概述]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Redis完整指南
+
+## 概述
+Redis是内存键值数据库,支持多种数据结构(字符串、哈希、列表、集合、有序集合)。用于缓存、会话存储、消息队列等场景。
+
+## 核心数据结构
+
+### 1. 字符串(String)
+
+```bash
+# 设置
+SET user:1 "Alice"
+SET user:2 "Bob" EX 3600  # 3600秒过期
+
+# 获取
+GET user:1
+
+# 批量操作
+MSET key1 "value1" key2 "value2"
+MGET key1 key2
+
+# 自增
+SET counter 0
+INCR counter
+INCRBY counter 10
+DECR counter
+
+# 追加
+APPEND user:1 " Smith"
+
+# 获取长度
+STRLEN user:1
+```
+
+### 2. 哈希(Hash)
+
+```bash
+# 设置字段
+HSET user:1 name "Alice" age 30 email "alice@example.com"
+
+# 获取字段
+HGET user:1 name
+HGETALL user:1
+HMGET user:1 name age
+
+# 删除字段
+HDEL user:1 age
+
+# 检查字段存在
+HEXISTS user:1 name
+
+# 自增
+HINCRBY user:1 age 1
+```
+
+### 3. 列表(List)
+
+```bash
+# 推入
+LPUSH queue "task1" "task2"  # 左边插入
+RPUSH queue "task3"          # 右边插入
+
+# 弹出
+LPOP queue  # 左边弹出
+RPOP queue  # 右边弹出
+
+# 获取范围
+LRANGE queue 0 -1  # 获取全部
+
+# 获取长度
+LLEN queue
+
+# 阻塞弹出
+BLPOP queue 5  # 5秒超时
+BRPOP queue 5
+```
+
+### 4. 集合(Set)
+
+```bash
+# 添加
+SADD tags "python" "redis" "docker"
+
+# 获取所有成员
+SMEMBERS tags
+
+# 检查存在
+SISMEMBER tags "python"
+
+# 删除
+SREM tags "docker"
+
+# 集合操作
+SADD set1 "a" "b" "c"
+SADD set2 "b" "c" "d"
+
+SINTER set1 set2  # 交集: b, c
+SUNION set1 set2  # 并集: a, b, c, d
+SDIFF set1 set2   # 差集: a
+```
+
+### 5. 有序集合(Sorted Set)
+
+```bash
+# 添加成员(带分数)
+ZADD leaderboard 100 "Alice" 95 "Bob" 87 "Carol"
+
+# 获取排名范围
+ZRANGE leaderboard 0 -1 WITHSCORES  # 升序
+ZREVRANGE leaderboard 0 -1 WITHSCORES  # 降序
+
+# 获取排名
+ZRANK leaderboard "Alice"  # 升序排名
+ZREVRANK leaderboard "Alice"  # 降序排名
+
+# 获取分数
+ZSCORE leaderboard "Alice"
+
+# 增加分数
+ZINCRBY leaderboard 10 "Alice"
+
+# 删除成员
+ZREM leaderboard "Carol"
+```
+
+## 高级功能
+
+### 1. 发布订阅(Pub/Sub)
+
+```bash
+# 订阅频道
+SUBSCRIBE channel1 channel2
+
+# 发布消息
+PUBLISH channel1 "Hello World"
+
+# 模式订阅
+PSUBSCRIBE news:*
+```
+
+### 2. 事务
+
+```bash
+MULTI
+SET key1 "value1"
+SET key2 "value2"
+INCR counter
+EXEC  # 执行
+# 或 DISCARD  # 取消
+```
+
+### 3. 过期时间
+
+```bash
+# 设置过期(秒)
+EXPIRE user:1 3600
+
+# 设置过期(毫秒)
+PEXPIRE user:1 3600000
+
+# 设置过期时间戳
+EXPIREAT user:1 1704067200
+
+# 查看剩余时间
+TTL user:1  # 秒
+PTTL user:1  # 毫秒
+
+# 取消过期
+PERSIST user:1
+```
+
+### 4. 持久化
+
+**RDB快照**:
+```bash
+# redis.conf
+save 900 1      # 900秒内至少1个key变化
+save 300 10     # 300秒内至少10个key变化
+save 60 10000   # 60秒内至少10000个key变化
+
+# 手动触发
+SAVE   # 阻塞
+BGSAVE  # 后台
+```
+
+**AOF日志**:
+```bash
+# redis.conf
+appendonly yes
+appendfsync everysec  # 每秒同步
+```
+
+## Python客户端
+
+```python
+import redis
+
+# 连接
+r = redis.Redis(host='localhost', port=6379, db=0)
+
+# 字符串
+r.set('user:1', 'Alice', ex=3600)
+name = r.get('user:1')
+
+# 哈希
+r.hset('user:1', mapping={
+    'name': 'Alice',
+    'age': 30,
+    'email': 'alice@example.com'
+})
+user = r.hgetall('user:1')
+
+# 列表
+r.lpush('queue', 'task1', 'task2')
+task = r.rpop('queue')
+
+# 集合
+r.sadd('tags', 'python', 'redis')
+tags = r.smembers('tags')
+
+# 有序集合
+r.zadd('leaderboard', {'Alice': 100, 'Bob': 95})
+top = r.zrevrange('leaderboard', 0, 9, withscores=True)
+
+# 发布订阅
+pubsub = r.pubsub()
+pubsub.subscribe('channel1')
+
+for message in pubsub.listen():
+    print(message)
+```
+
+## 最佳实践
+
+### ✅ DO
+
+1. **使用连接池**
+```python
+pool = redis.ConnectionPool(
+    host='localhost',
+    port=6379,
+    max_connections=100
+)
+r = redis.Redis(connection_pool=pool)
+```
+
+2. **使用Pipeline批量操作**
+```python
+pipe = r.pipeline()
+for i in range(1000):
+    pipe.set(f'key:{i}', i)
+pipe.execute()
+```
+
+3. **设置合理的过期时间**
+```python
+r.set('session:user:123', data, ex=3600)  # 1小时
+```
+
+### ❌ DON'T
+
+1. **不要使用KEYS命令**
+```python
+# ❌ 差(阻塞)
+keys = r.keys('*')
+
+# ✅ 好(使用SCAN)
+for key in r.scan_iter('*'):
+    print(key)
+```
+
+2. **不要存储大对象**
+```python
+# ❌ 差
+r.set('big:data', huge_json)  # 几MB
+
+# ✅ 好: 分片存储
+for i, chunk in enumerate(chunks):
+    r.set(f'big:data:{i}', chunk)
+```
+
+## 学习路径
+
+### 初级 (1周)
+1. 基本数据结构
+2. 常用命令
+3. 过期时间
+
+### 中级 (1-2周)
+1. 持久化(RDB/AOF)
+2. 发布订阅
+3. 事务
+
+### 高级 (2-3周)
+1. 集群和分片
+2. Lua脚本
+3. 性能优化
+
+---
+
+**知识ID**: `redis-complete`  
+**领域**: development  
+**类型**: standards  
+**难度**: intermediate  
+**质量分**: 93  
+**维护者**: dba-team@umadev.com  
+**最后更新**: 2026-03-28

package/development/01-standards/rest-api-complete.md

@@ -0,0 +1,316 @@
+---
+id: rest-api-complete
+title: RESTful API设计完整指南
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [api, complete, development, rest, 学习路径, 最佳实践, 核心原则, 概述]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# RESTful API设计完整指南
+
+## 概述
+REST是Web API架构风格,使用HTTP方法操作资源。本指南覆盖REST原则、端点设计、状态码、版本控制和最佳实践。
+
+## 核心原则
+
+### 1. REST约束
+
+- 客户端-服务器分离
+- 无状态(Stateless)
+- 可缓存(Cacheable)
+- 统一接口(Uniform Interface)
+- 分层系统(Layered System)
+
+### 2. 资源和端点
+
+**资源命名**:
+```
+# ✅ 好 - 使用名词复数
+GET    /users
+GET    /users/{id}
+POST   /users
+PUT    /users/{id}
+DELETE /users/{id}
+
+# 嵌套资源
+GET    /users/{id}/posts
+POST   /users/{id}/posts
+
+# ❌ 差 - 使用动词
+GET    /getUsers
+POST   /createUser
+```
+
+### 3. HTTP方法
+
+```python
+from fastapi import FastAPI, HTTPException
+
+app = FastAPI()
+
+# 获取资源集合
+@app.get('/users')
+async def list_users(skip: int = 0, limit: int = 10):
+    return users[skip:skip+limit]
+
+# 获取单个资源
+@app.get('/users/{user_id}')
+async def get_user(user_id: int):
+    user = db.get(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail='User not found')
+    return user
+
+# 创建资源
+@app.post('/users', status_code=201)
+async def create_user(user: UserCreate):
+    new_user = db.create(user)
+    return new_user
+
+# 完整更新
+@app.put('/users/{user_id}')
+async def update_user(user_id: int, user: UserUpdate):
+    updated = db.update(user_id, user)
+    if not updated:
+        raise HTTPException(status_code=404)
+    return updated
+
+# 部分更新
+@app.patch('/users/{user_id}')
+async def partial_update_user(user_id: int, user: UserPatch):
+    updated = db.partial_update(user_id, user)
+    return updated
+
+# 删除资源
+@app.delete('/users/{user_id}', status_code=204)
+async def delete_user(user_id: int):
+    db.delete(user_id)
+    return None
+```
+
+### 4. 状态码
+
+**成功响应**:
+```
+200 OK - 成功
+201 Created - 资源创建成功
+204 No Content - 删除成功,无返回内容
+```
+
+**客户端错误**:
+```
+400 Bad Request - 请求格式错误
+401 Unauthorized - 未认证
+403 Forbidden - 无权限
+404 Not Found - 资源不存在
+409 Conflict - 资源冲突
+422 Unprocessable Entity - 验证失败
+429 Too Many Requests - 限流
+```
+
+**服务器错误**:
+```
+500 Internal Server Error - 服务器错误
+503 Service Unavailable - 服务不可用
+```
+
+### 5. 过滤、排序、分页
+
+```python
+@app.get('/articles')
+async def list_articles(
+    status: Optional[str] = None,
+    author: Optional[int] = None,
+    sort: str = 'created_at',
+    order: str = 'desc',
+    page: int = 1,
+    per_page: int = 20
+):
+    query = db.query(Article)
+    
+    # 过滤
+    if status:
+        query = query.filter(Article.status == status)
+    if author:
+        query = query.filter(Article.author_id == author)
+    
+    # 排序
+    sort_field = getattr(Article, sort)
+    if order == 'desc':
+        query = query.order_by(sort_field.desc())
+    else:
+        query = query.order_by(sort_field.asc())
+    
+    # 分页
+    total = query.count()
+    items = query.offset((page - 1) * per_page).limit(per_page).all()
+    
+    return {
+        'items': items,
+        'total': total,
+        'page': page,
+        'per_page': per_page,
+        'pages': (total + per_page - 1) // per_page
+    }
+```
+
+### 6. 版本控制
+
+**URL版本控制**:
+```python
+@app.get('/v1/users')
+async def list_users_v1():
+    pass
+
+@app.get('/v2/users')
+async def list_users_v2():
+    pass
+```
+
+**Header版本控制**:
+```python
+@app.get('/users')
+async def list_users(version: str = Header(default='1.0')):
+    if version == '2.0':
+        return v2_response()
+    return v1_response()
+```
+
+### 7. HATEOAS
+
+```python
+@app.get('/users/{user_id}')
+async def get_user(user_id: int, request: Request):
+    user = db.get(user_id)
+    
+    # 添加链接
+    return {
+        'data': user,
+        '_links': {
+            'self': {'href': str(request.url)},
+            'posts': {'href': f'/users/{user_id}/posts'},
+            'update': {'href': f'/users/{user_id}', 'method': 'PUT'},
+            'delete': {'href': f'/users/{user_id}', 'method': 'DELETE'}
+        }
+    }
+```
+
+### 8. 错误处理
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+class APIError(Exception):
+    def __init__(self, status_code: int, message: str, details: dict = None):
+        self.status_code = status_code
+        self.message = message
+        self.details = details or {}
+
+@app.exception_handler(APIError)
+async def api_error_handler(request: Request, exc: APIError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            'error': {
+                'code': exc.status_code,
+                'message': exc.message,
+                'details': exc.details
+            }
+        }
+    )
+
+# 使用
+@app.get('/users/{user_id}')
+async def get_user(user_id: int):
+    user = db.get(user_id)
+    if not user:
+        raise APIError(404, 'User not found', {'user_id': user_id})
+    return user
+```
+
+## 最佳实践
+
+### ✅ DO
+
+1. **使用复数名词**
+```
+✅ /users, /posts, /comments
+❌ /user, /post, /comment
+```
+
+2. **返回适当状态码**
+```python
+# ✅ 好
+@app.post('/users', status_code=201)
+async def create_user():
+    pass
+
+# ❌ 差 - 总是返回200
+@app.post('/users')
+async def create_user():
+    return {'status': 'created'}
+```
+
+3. **支持内容协商**
+```python
+@app.get('/users')
+async def list_users(accept: str = Header(default='application/json')):
+    users = get_users()
+    
+    if accept == 'application/xml':
+        return XMLResponse(users)
+    
+    return users
+```
+
+### ❌ DON'T
+
+1. **不要在URL中使用动词**
+```
+❌ /users/create
+❌ /users/delete/{id}
+```
+
+2. **不要返回敏感信息**
+```python
+# ❌ 差
+{
+    'password': 'hashed_value',
+    'api_key': 'secret'
+}
+
+# ✅ 好
+{
+    'email': 'user@example.com'
+}
+```
+
+## 学习路径
+
+### 初级 (1周)
+1. REST原则
+2. HTTP方法
+3. 资源命名
+
+### 中级 (1-2周)
+1. 状态码
+2. 过滤分页
+3. 版本控制
+
+### 高级 (2-3周)
+1. HATEOAS
+2. 内容协商
+3. API文档
+
+---
+
+**知识ID**: `rest-api-complete`  
+**领域**: development  
+**类型**: standards  
+**难度**: intermediate  
+**质量分**: 94  
+**维护者**: api-team@umadev.com  
+**最后更新**: 2026-03-28