1.1 定义

1、基础接口：单一职责原则，每个接口只负责各自的业务，下接db，通用性强。

2、聚合接口：根据调用方需求聚合基础接口数据，业务性强。

1.2 协议

1. 客户端在通过 API 与后端服务通信的过程中， 应该使用 HTTPS（生产环境） 协议

2. 服务端响应的数据格式统一为JSON

1.3域名host

prd环境：https://xxx-xxx-api.example.com/

uat环境：https://xxx-xxx-api-uat.example.com/

test环境：https://xxx-xxx-api-test.example.com/

dev环境：https://xxx-xxx-api-dev.example.com/

将api放到子域名里，这种做法可以保持某些规模化上的灵活性。

1.4路径path

path命名应该是以资源为导向的命名，对资源的操作是由HttpMethod（get、post、put、delete）来决定。所以一般来说url上的单词都应该是名词，一定不要是动词。一般遵循以下约定：

（1）URL 的命名必须全部小写；
（2） URL 必须 是易读的 URL；
（3）一定不可 暴露服务器架构

（4）出现复合词汇使用下划线分隔，例如：animal_types

举几个正面例子：

新增用户：http://localhost/user post方法提交;

修改用户：http://localhost/users put方法提交;

删除文章：http://localhost/articles?author=1&category=2 delete方法提交;

查询用户：http://localhost/users get方法提交;

查询文章：http://localhost/articles?author=1&category=2get方法提交;

错误的例子如下：

http://localhost/get_user

https://api.example.com/getUserInfo?userid=1

https://api.example.com/getusers

https://api.example.com/sv/u

https://api.example.com/cgi-bin/users/get_user.php?userid=1

1.5动词

1. RESTful 的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构，动词通常就是四种 HTTP 方法，对应 CRUD 操作：
   
   

其中

 (1)删除资源 必须 用 DELETE 方法

 (2)创建新的资源 必须 使用 POST 方法

 (3)更新资源 应该 使用 PUT 方法

 (4)获取资源信息 必须 使用 GET 方法

针对每一个路径来说，下面列出所有可行的 HTTP 动词和端点的组合

GET /trades?status=closed&sort=sortby=name&order=asc

#   可为其定制快捷方式

GET /trades/recently_closed

1、SartUp类里添加代码-- httpclient初始化：
   services.AddHttpClient("MsgApi", c =>
            {
                c.BaseAddress = new Uri(Configuration["OuterApi:MsgApi:url"]);
                c.Timeout = TimeSpan.FromSeconds(30);
            });

//2 构造函注入
private IDbContext _dbContext;
private IUnitOfWork _unitOfWork;
private IordersRepository _ordersRepository;
private IordercourseRepository _ordercourseRepository;
private ILogger _logger;
privatereadonly IConfiguration _config;
privatereadonly IHttpClientFactory _clientFactory;

public ordersService(IDbContext dbContext, ILogger logger, IConfiguration config, IHttpClientFactory clientFactory)
        {
            _dbContext = dbContext;
            _unitOfWork = new UnitOfWork(_dbContext);
            _ordersRepository = new ordersRepository(_dbContext);
            _ordercourseRepository = new ordercourseRepository(_dbContext);
            _mapper = mapper;
            _config = config;
            _logger = logger;
            _clientFactory = clientFactory;
        }

//3使用 
///

///判断此时该校区是否可以下单
///
///
///
publicasync Taskstring>> CheckDept(CheckSchoolDeptReq req)
        {
            Resultstring> sendRet = new Resultstring>();
try
            {
                HttpClient client = _clientFactory.CreateClient("ContractApi");
                MyHttpClientHelper myHttpClientHelper = new MyHttpClientHelper();
                MarketToUPCCheckReq checkreq = new MarketToUPCCheckReq();
                sendRet = await myHttpClientHelper.GetDatastring>>(client, "MarketToUPCCheck", checkreq);
            }
catch (Exception ex)
            {
                sendRet.state = false;
                sendRet.error_code = ErrorCode.SysExceptionError;
                sendRet.error_msg = "调用《是否可以下订单接口》报错了。请重试或者联系管理员！";
                _logger.LogError(ex, ErrorCode.SysExceptionError +"调用《是否可以下订单》接口报错了：" + ex.Message);
            }

return sendRet;
        }

 /// 

    /// 记录日志用过滤器
    /// 
    public class LogstashFilter : IActionFilter, IResultFilter
    {
        private string ActionArguments { get; set; }

        /// 

        /// 请求体中的所有值
        /// 
        private string RequestBody { get; set; }
        private Stopwatch Stopwatch { get; set; }

        private ILogger _logger;
      
        public LogstashFilter(ILogger logger )
        {
            _logger = logger;
            
        }

        /// 

        /// Action 调用前执行
        /// 
        /// 
        public void OnActionExecuting(ActionExecutingContext context)
        {
              
            long contentLen = context.HttpContext.Request.ContentLength == null ? 0 : context.HttpContext.Request.ContentLength.Value;
            if (contentLen > 0)
            {
                // 读取请求体中所有内容
                System.IO.Stream stream = context.HttpContext.Request.Body;
                if (context.HttpContext.Request.Method == "POST")
                {
                    stream.Position = 0;
                }
                byte[] buffer = new byte[contentLen];
                stream.Read(buffer, 0, buffer.Length);

                RequestBody = System.Text.Encoding.UTF8.GetString(buffer);// 转化为字符串
            }

            ActionArguments = JsonConvert.SerializeObject(context.ActionArguments);

            Stopwatch = new Stopwatch();
            Stopwatch.Start();


            string url = context.HttpContext.Request.Host + context.HttpContext.Request.Path + context.HttpContext.Request.QueryString;
            string method = context.HttpContext.Request.Method;
           
            _logger.LogInformation($"地址：{url} \n " +
               $"方式：{method} \n " +
               $"请求体：{RequestBody} \n " +
               $"完整参数：{ActionArguments}\n " );


        }

        /// 

        /// Action 方法调用后，Result 方法调用前执行
        /// 
        /// 
        public void OnActionExecuted(ActionExecutedContext context)
        {
            // do nothing
        }

        /// 

        /// Result 方法调用前（View 呈现前）执行
        /// 
        /// 
        public void OnResultExecuting(ResultExecutingContext context)
        {
            // do nothing
        }

        /// 

        /// Result 方法调用后执行
        /// 
        /// 
        public void OnResultExecuted(ResultExecutedContext context)
        {

            Stopwatch.Stop();
            string url = context.HttpContext.Request.Host + context.HttpContext.Request.Path + context.HttpContext.Request.QueryString;
                string method = context.HttpContext.Request.Method;
                string qs = ActionArguments;
                string res = "在返回结果前发生了异常";
                if (context.Result is ObjectResult)
                {
                    dynamic result = context.Result.GetType().Name == "EmptyResult" ? new { Value = "无返回结果" } : context.Result as dynamic;
                    if (result != null)
                    {
                        res = JsonConvert.SerializeObject(result.Value);
                    }

                }

                _logger.LogInformation($"地址：{url} \n " +
                    $"方式：{method} \n " +
                    $"请求体：{RequestBody} \n " +
                    $"参数：{qs}\n " +
                    $"结果：{res}\n " +
                    $"耗时：{Stopwatch.Elapsed.TotalMilliseconds} 毫秒");

            
        }
    }

catch (Exception ex)
            { 
                _logger.LogError(ex, ErrorCode500 + ex.Message);
            }